Surfaces

Stable - @kikita-labs/ui v2.0.0

Stepper

Multi-step progress and navigation for guided flows.

Import

Stepper composes a container and projected step components.

stepper.ts
import { KuiStep, KuiStepper } from '@kikita-labs/ui';

Usage

Open in Playground

Bind currentIndex with a signal and describe each step with labels.

DetailsProject basics 2 TeamInvite collaborators 3 ReviewConfirm settings
<div class="basic-stepper-example">
  <kui-stepper [(currentIndex)]="currentIndex">
    <kui-step label="Details" description="Project basics" />
    <kui-step label="Team" description="Invite collaborators" />
    <kui-step label="Review" description="Confirm settings" />
  </kui-stepper>
</div>

Provider defaults

Set defaults.stepper once for the application or for a subtree. Each option resolves as local input > defaults.stepper.<option> > built-in default.

import { provideKikitaUi } from '@kikita-labs/ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideKikitaUi({
      defaults: {
        stepper: {
          /* options below */
        },
      },
    }),
  ],
};
NameTypeDefaultDescription
size'sm' | 'md' | 'lg' — Component size. Takes precedence over the global defaults.size.
orientation'horizontal' | 'vertical' — Default orientation.
linearboolean — Requires steps to be completed in order.
compactboolean — Uses the compact layout.

Theming tokens

Set any of these on the component or an ancestor to restyle one part. Each token is optional: when it is not set, the part uses the role or scale token in the default column.

NameTypeDefaultDescription
--kui-stepper-label-color-hoverCSS custom property--kui-color-textLabel color, hover
--kui-stepper-circle-focus-ring-colorCSS custom property--kui-color-focusCircle focus ring color
--kui-stepper-label-colorCSS custom property--kui-color-text-secondaryLabel color
--kui-stepper-description-colorCSS custom property--kui-color-text-secondaryDescription color
--kui-stepper-circle-color-doneCSS custom property--kui-color-primary-on-fillCircle color, done
--kui-stepper-label-color-doneCSS custom property--kui-color-textLabel color, done
--kui-stepper-circle-bg-currentCSS custom property--kui-color-surfaceCircle background, current
--kui-stepper-label-color-currentCSS custom property--kui-color-textLabel color, current
--kui-stepper-circle-bg-upcomingCSS custom property--kui-color-surface-elevatedCircle background, upcoming
--kui-stepper-circle-border-upcomingCSS custom property--kui-color-border-controlCircle border color, upcoming
--kui-stepper-circle-bg-disabledCSS custom property--kui-color-surface-elevatedCircle background, disabled
--kui-stepper-circle-border-disabledCSS custom property--kui-color-borderCircle border color, disabled
--kui-stepper-circle-color-disabledCSS custom property--kui-color-text-disabledCircle color, disabled
--kui-stepper-label-color-disabledCSS custom property--kui-color-text-disabledLabel color, disabled
--kui-stepper-circle-color-errorCSS custom property--kui-color-danger-on-fillCircle color, error
--kui-stepper-circle-bg-compactCSS custom property--kui-color-borderCircle background, compact
NameTypeDefaultDescription
--kui-stepper-gap-verticalCSS custom property--kui-space-3Gap, vertical
--kui-stepper-body-padding-bottom-verticalCSS custom property--kui-space-5Body padding, bottom vertical
--kui-stepper-circle-font-sizeCSS custom property--kui-text-sm-sizeCircle font size
--kui-stepper-label-font-sizeCSS custom property--kui-text-sm-sizeLabel font size
--kui-stepper-description-font-sizeCSS custom property--kui-text-xs-sizeDescription font size
--kui-stepper-circle-font-size-smCSS custom property--kui-text-xs-sizeCircle font size, sm
--kui-stepper-label-font-size-smCSS custom property--kui-text-xs-sizeLabel font size, sm
--kui-stepper-circle-font-size-lgCSS custom property--kui-text-base-sizeCircle font size, lg
--kui-stepper-label-font-size-lgCSS custom property--kui-text-base-sizeLabel font size, lg
--kui-stepper-dot-sizeCSS custom property10pxCompact dot size

Messages

Every text the component owns (accessible names, visible words, announcements) is a typed message with an English default. Override it for the application with provideKikitaUi({ messages }), or for a subtree with provideKuiMessages.

NameTypeDefaultDescription
backToStepKuiMessageFn<{ label: string; }> — Name of the button of a finished step. Default Back to step {label}.
goToStepKuiMessageFn<{ label: string; }> — Name of the button of an upcoming step. Default Go to step {label}.

API

Inputs verified against @kikita-labs/ui v2.0.0 public typings.

NameTypeDefaultDescription
[(currentIndex)]number0Zero-based active step index.
orientation'horizontal' | 'vertical' | undefinedundefinedStep list layout direction. Falls back to defaults.stepper.orientation, then horizontal.
size'sm' | 'md' | 'lg' | undefinedundefinedCircle size and label scale. Falls back to defaults.stepper.size, then the root size, then md.
linearboolean | undefinedundefinedWhen true, only completed steps can be clicked to go back; when false, upcoming steps can be clicked to jump forward. Falls back to defaults.stepper.linear, then true.
compactboolean | undefinedundefinedShows step circles (dots) without labels or descriptions. Falls back to defaults.stepper.compact, then false.
kui-step.labelstring''Primary step label.
kui-step.descriptionstring''Optional secondary line below the label.
kui-step.hasErrorbooleanfalseMarks the step as errored and disables later steps.
kui-step.disabledbooleanfalseForces a step to render disabled.
--kui-stepper-connector-colorCSS custom property-Connector line colour.
--kui-stepper-connector-color-doneCSS custom property-Connector line colour after a completed step.
--kui-stepper-circle-sizeCSS custom property-Step circle diameter.
--kui-stepper-fg-upcomingCSS custom property-Foreground of an upcoming step.
--kui-stepper-fg-currentCSS custom property-Foreground of the current step.
--kui-stepper-fg-doneCSS custom property-Foreground of a completed step.
--kui-stepper-fg-errorCSS custom property-Foreground of an errored step.
KuiStepperOptionsinterface-Shape of defaults.stepper: size, orientation, linear and compact.

Accessibility

Stepper exposes progress state through native buttons and clear labels.

  • kui-stepper renders role="list" and each kui-step renders role="listitem"; pass aria-label on the host, for example Progress.
  • The current step has aria-current="step".
  • Completed steps (and upcoming steps when linear is false) render their circle as a native button named by the stepper.backToStep and stepper.goToStep messages; disabled steps are plain spans out of the tab order.
  • Connector lines are decorative (aria-hidden="true").
  • Use descriptive labels and optional descriptions for each step.
  • Linear mode prevents activating upcoming steps.
  • Error steps disable later steps until the flow recovers.
  • Use vertical orientation when labels need more horizontal space.

Migrating to 2.0

Consumer-visible changes of @kikita-labs/ui 2.0 for Stepper.

  • The classes are KuiStepper and KuiStep; the Component suffix is gone.
  • Size, orientation, linear and compact defaults moved to provideKuiDefaults({ stepper: { ... } }); the inputs are now undefined until set.
  • The back and go-to button names come from the stepper.backToStep and stepper.goToStep messages.
  • Every colour part has a token, plus font-size, gap and dot-size geometry tokens.