Skip to main content

Stepper

Guide users through a sequence of panels and completion states.

Step 1: Set up your profile and login credentials.

Props
Slots

Anatomy#

Stepper [component; slot=root]
├── header [slot]
│   └── item [slot]
│       ├── trigger [slot]
│       │   ├── indicator [slot]
│       │   │   └── icon [internal]
│       │   └── wrapper [slot]
│       │       ├── label [slot]
│       │       └── description [slot]
│       └── separator [slot]
└── content [slot]

The indicator, label, and description share one trigger; separators appear only between items.

Usage#

Use Stepper to show progress through a fixed sequence of steps. Decide how far users may jump ahead with navigation. Use Tabs for peer panels that are not a sequence. Use Pagination for a result set with a known page count.

import { Stepper } from 'moraine'

export function Example() {
  return (
    <Stepper
      items={[
        { value: 'details', label: 'Details' },
        { value: 'review', label: 'Review' },
      ]}
    />
  )
}

navigation (default 'none') controls which steps users can activate from their triggers:

  • none enables only the active step, so the flow moves through your own controls.
  • linear enables completed steps and the next step, so later steps stay locked until earlier ones are reached.
  • free enables every enabled step.

onValueChange fires only when the user activates a different step from a trigger, so in practice only in linear and free. It does not fire for programmatic value changes. To drive the flow from your own Previous and Next buttons, control value and update it in those handlers. Set disabled on the Stepper to block every trigger.

<Stepper items={STEPS} value={step()} onValueChange={setStep} navigation="linear" />

Panels and orientation#

Step triggers and panels use tab semantics (tablist, tab, tabpanel). Every item requires a unique value; an item that repeats an earlier value renders disabled and logs a development warning. item.content is static JSX or a component that receives { value, index }; only the active step’s panel renders, and a step without content has no panel. Vertical orientation changes the layout and the arrow keys that move between steps. Stepper marks every step before the active one as completed, based on item order. Set item.icon to replace the step number in the indicator.

<Stepper
  defaultValue="details"
  orientation="vertical"
  items={[
    { value: 'details', label: 'Project details', content: () => <ProjectForm /> },
    { value: 'target', label: 'Deploy target', content: () => <TargetForm /> },
  ]}
/>

Keyboard interaction#

activationMode controls whether arrow-key focus activates a step immediately (automatic, the default) or only moves focus until ↵ or Space confirms it (manual). Disabled and navigation-locked steps are skipped. Navigation stops at the first and last step unless you set loop.

Key Description
→ / ← Moves to the next or previous enabled step in horizontal orientation.
↓ / ↑ Moves to the next or previous enabled step in vertical orientation.
↖ / ↘ Moves to the first or last enabled step.
↵ / Space Activates the focused step in manual activation mode.

Examples#

Onboard with Previous and Next#

Keep the flow linear. Move between Account, Profile, and Review from application buttons.

import { Button, Stepper } from 'moraine'
import type { StepperT } from 'moraine'
import { createSignal } from 'solid-js'

const STEPS = [
  { value: 'account', label: 'Account', description: 'User credentials' },
  { value: 'profile', label: 'Profile', description: 'Personal details' },
  { value: 'review', label: 'Review', description: 'Confirmation' },
] satisfies StepperT.Item[]

export function LinearUsage() {
  const [step, setStep] = createSignal('account')
  const stepKeys = ['account', 'profile', 'review']

  const currentIndex = () => stepKeys.indexOf(step())

  const goPrev = () => {
    const prevKey = stepKeys[Math.max(0, currentIndex() - 1)]
    if (prevKey) {
      setStep(prevKey)
    }
  }

  const goNext = () => {
    const nextKey = stepKeys[Math.min(stepKeys.length - 1, currentIndex() + 1)]
    if (nextKey) {
      setStep(nextKey)
    }
  }

  return (
    <div class="max-w-xl w-full space-y-4">
      <Stepper items={STEPS} value={step()} onValueChange={setStep} />
      <div class="flex gap-2">
        <Button size="xs" variant="outline" disabled={currentIndex() === 0} onClick={goPrev}>
          Previous
        </Button>
        <Button size="xs" disabled={currentIndex() === stepKeys.length - 1} onClick={goNext}>
          Next step
        </Button>
      </div>
    </div>
  )
}

One setup panel at a time#

Attach content to each step so only the active panel is shown.

import { Stepper } from 'moraine'

export function PanelsUsage() {
  return (
    <div class="max-w-md w-full">
      <Stepper
        defaultValue="details"
        items={[
          {
            value: 'details',
            label: 'Project details',
            content: (
              <div class="text-xs text-muted-foreground p-4">
                Configure project name and workspace root.
              </div>
            ),
          },
          {
            value: 'target',
            label: 'Deploy target',
            content: (
              <div class="text-xs text-muted-foreground p-4">
                Select cloud provider and cluster region.
              </div>
            ),
          },
        ]}
      />
    </div>
  )
}

Jump around a release workflow#

Control Draft, Review, and Ship from page state with the buttons below.

import { Button, Stepper } from 'moraine'
import { createSignal } from 'solid-js'

export function ControlledNonLinear() {
  const RELEASE_STEPS = () => [
    {
      label: 'Draft',
      value: 'draft',
      content: <p class="text-sm text-foreground">Prepare release notes.</p>,
    },
    {
      label: 'Review',
      value: 'review',
      content: <p class="text-sm text-foreground">Collect team approvals.</p>,
    },
    {
      label: 'Ship',
      value: 'ship',
      content: <p class="text-sm text-foreground">Deploy to production.</p>,
    },
  ]

  const [releaseStep, setReleaseStep] = createSignal('review')

  return (
    <div class="space-y-4">
      <Stepper items={RELEASE_STEPS()} value={releaseStep()} onValueChange={setReleaseStep} />
      <div class="flex flex-wrap gap-2 items-center">
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('draft')}>
          Go to draft
        </Button>
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('review')}>
          Go to review
        </Button>
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('ship')}>
          Go to ship
        </Button>
        <p class="text-xs text-muted-foreground">Current step: {releaseStep()}</p>
      </div>
    </div>
  )
}

Compare navigation modes#

Choose a navigation mode to see which checkout steps can be activated.

import { Button, Stepper } from 'moraine'
import type { StepperT } from 'moraine'
import { For, createSignal } from 'solid-js'

type Navigation = NonNullable<StepperT.Base['navigation']>

const NAVIGATION_MODES: Navigation[] = ['none', 'linear', 'free']

export function NavigationModes() {
  const [navigation, setNavigation] = createSignal<Navigation>('linear')
  const checkoutSteps = [
    {
      label: 'Address',
      description: 'Where should we send the order?',
      icon: 'i-lucide:map-pinned',
      value: 'address',
      content: <p class="text-sm text-foreground">Collect shipping address details.</p>,
    },
    {
      label: 'Shipping',
      description: 'Choose a delivery method.',
      icon: 'i-lucide:truck',
      value: 'shipping',
      content: <p class="text-sm text-foreground">Pick standard, express, or local pickup.</p>,
    },
    {
      label: 'Payment',
      description: 'Confirm billing and payment.',
      icon: 'i-lucide:credit-card',
      value: 'payment',
      content: <p class="text-sm text-foreground">Review billing details and submit payment.</p>,
    },
  ] satisfies StepperT.Item[]

  return (
    <div class="space-y-4">
      <div class="flex flex-wrap gap-2">
        <For each={NAVIGATION_MODES}>
          {(mode) => (
            <Button
              size="xs"
              variant={navigation() === mode ? 'solid' : 'outline'}
              onClick={() => setNavigation(mode)}
            >
              {mode}
            </Button>
          )}
        </For>
      </div>

      <Stepper items={checkoutSteps} defaultValue="address" navigation={navigation()} />
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-disabled
Slot: stepper-itemstepper-separator
Description: Present when the component, slot, or item is disabled.
data-state
Slot: stepper-itemstepper-triggerstepper-indicatorstepper-separator
Description: Stores the component state used by styling hooks (e.g. open, closed, active).
data-clickable
Slot: stepper-trigger
Description: Present when the step or item accepts direct activation.
data-selected
Slot: stepper-triggerstepper-content
Description: Present when the item or tab is selected.

Props#

Props for the Stepper component. Renders a <div> element by default.

Prop