navigationstepper

Stepper

Tab-structured step navigation with configurable orientation and separator layout.

Import#

import { Stepper } from 'moraine'

Slot Structure#

Header with step items and optional per-step content panels.

root
├── header
│   └── item (×n)
│       ├── container
│       │   ├── trigger
│       │   └── separator (optional, between items)
│       └── wrapper (optional)
│           ├── title (optional)
│           └── description (optional)
└── content (×n, optional)

Examples#

Sizes#

Preview the Stepper across all supported sizes using the default linear, non-clickable tab navigation.

1
function Sizes() {
2
  const createCheckoutSteps = () => [
3
    {
4
      title: 'Address',
5
      description: 'Where should we send the order?',
6
      icon: 'i-lucide:map-pinned',
7
      value: 'address',
8
      content: <p class="text-sm text-foreground">Collect shipping address details.</p>,
9
    },
10
    {
11
      title: 'Shipping',
12
      description: 'Choose a delivery method.',
13
      icon: 'i-lucide:truck',
14
      value: 'shipping',
15
      content: <p class="text-sm text-foreground">Pick standard, express, or local pickup.</p>,
16
    },
17
    {
18
      title: 'Payment',
19
      description: 'Confirm billing and payment.',
20
      icon: 'i-lucide:credit-card',
21
      value: 'payment',
22
      content: <p class="text-sm text-foreground">Review billing details and submit payment.</p>,
23
    },
24
  ]
25

26
  const STEPPER_SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const
27

28
  return (
29
    <div class="space-y-6">
30
      <For each={STEPPER_SIZES}>
31
        {(size) => (
32
          <div class="space-y-2">
33
            <p class="text-xs text-muted-foreground tracking-wide font-medium uppercase">{size}</p>
34
            <Stepper items={createCheckoutSteps()} defaultValue="shipping" size={size} />
35
          </div>
36
        )}
37
      </For>
38
    </div>
39
  )
40
}

Controlled + Non-linear#

Manage the active step externally and allow jumping to any step.

1
function ControlledNonLinear() {
2
  const RELEASE_STEPS = () => [
3
    {
4
      title: 'Draft',
5
      value: 'draft',
6
      content: <p class="text-sm text-foreground">Prepare release notes.</p>,
7
    },
8
    {
9
      title: 'Review',
10
      value: 'review',
11
      content: <p class="text-sm text-foreground">Collect team approvals.</p>,
12
    },
13
    {
14
      title: 'Ship',
15
      value: 'ship',
16
      content: <p class="text-sm text-foreground">Deploy to production.</p>,
17
    },
18
  ]
19

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

22
  return (
23
    <div class="space-y-4">
24
      <Stepper
25
        items={RELEASE_STEPS()}
26
        value={releaseStep()}
27
        onChange={setReleaseStep}
28
        linear={false}
29
      />
30
      <div class="flex flex-wrap gap-2 items-center">
31
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('draft')}>
32
          Go to draft
33
        </Button>
34
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('review')}>
35
          Go to review
36
        </Button>
37
        <Button size="sm" variant="outline" onClick={() => setReleaseStep('ship')}>
38
          Go to ship
39
        </Button>
40
        <p class="text-xs text-muted-foreground">Current step: {releaseStep()}</p>
41
      </div>
42
    </div>
43
  )
44
}

Clickable vs Non-Clickable#

Compare the default non-clickable mode with explicit click-enabled navigation.

1
function ClickableVsReadOnly() {
2
  const createCheckoutSteps = () => [
3
    {
4
      title: 'Address',
5
      description: 'Where should we send the order?',
6
      icon: 'i-lucide:map-pinned',
7
      value: 'address',
8
      content: <p class="text-sm text-foreground">Collect shipping address details.</p>,
9
    },
10
    {
11
      title: 'Shipping',
12
      description: 'Choose a delivery method.',
13
      icon: 'i-lucide:truck',
14
      value: 'shipping',
15
      content: <p class="text-sm text-foreground">Pick standard, express, or local pickup.</p>,
16
    },
17
    {
18
      title: 'Payment',
19
      description: 'Confirm billing and payment.',
20
      icon: 'i-lucide:credit-card',
21
      value: 'payment',
22
      content: <p class="text-sm text-foreground">Review billing details and submit payment.</p>,
23
    },
24
  ]
25

26
  return (
27
    <div class="space-y-6">
28
      <div class="space-y-2">
29
        <p class="text-xs text-muted-foreground tracking-wide font-medium uppercase">
30
          Default (`linear=true`, `clickable=false`)
31
        </p>
32
        <Stepper items={createCheckoutSteps()} defaultValue="address" />
33
      </div>
34

35
      <div class="space-y-2">
36
        <p class="text-xs text-muted-foreground tracking-wide font-medium uppercase">
37
          Click enabled (`linear=true`, `clickable=true`)
38
        </p>
39
        <Stepper items={createCheckoutSteps()} defaultValue="address" clickable />
40
      </div>
41

42
      <div class="space-y-2">
43
        <p class="text-xs text-muted-foreground tracking-wide font-medium uppercase">
44
          Non-linear (`linear=false`, `clickable=true`)
45
        </p>
46
        <Stepper items={createCheckoutSteps()} defaultValue="address" linear={false} clickable />
47
      </div>
48
    </div>
49
  )
50
}

Linear Checkout#

Enable clicking while still only allowing the next available step to be selected.

1
function LinearCheckout() {
2
  const createCheckoutSteps = () => [
3
    {
4
      title: 'Address',
5
      description: 'Where should we send the order?',
6
      icon: 'i-lucide:map-pinned',
7
      value: 'address',
8
      content: <p class="text-sm text-foreground">Collect shipping address details.</p>,
9
    },
10
    {
11
      title: 'Shipping',
12
      description: 'Choose a delivery method.',
13
      icon: 'i-lucide:truck',
14
      value: 'shipping',
15
      content: <p class="text-sm text-foreground">Pick standard, express, or local pickup.</p>,
16
    },
17
    {
18
      title: 'Payment',
19
      description: 'Confirm billing and payment.',
20
      icon: 'i-lucide:credit-card',
21
      value: 'payment',
22
      content: <p class="text-sm text-foreground">Review billing details and submit payment.</p>,
23
    },
24
  ]
25

26
  return <Stepper items={createCheckoutSteps()} defaultValue="address" clickable />
27
}

Vertical#

Render the tab-structured step navigation vertically.

1
function Vertical() {
2
  const PIPELINE_STEPS = () => [
3
    {
4
      title: 'Queued',
5
      description: 'Waiting for worker capacity.',
6
      value: 'queued',
7
      content: <p class="text-sm text-foreground">This job is waiting in the queue.</p>,
8
    },
9
    {
10
      title: 'Building',
11
      description: 'Compiling and bundling assets.',
12
      value: 'building',
13
      content: <p class="text-sm text-foreground">The current build is running.</p>,
14
    },
15
    {
16
      title: 'Ready',
17
      description: 'Artifacts are available.',
18
      value: 'ready',
19
      content: <p class="text-sm text-foreground">The deployment artifact is ready to use.</p>,
20
    },
21
  ]
22

23
  return (
24
    <div class="max-w-3xl">
25
      <Stepper items={PIPELINE_STEPS()} orientation="vertical" defaultValue="building" />
26
    </div>
27
  )
28
}

API Reference#

Attributes#

Slotroot0 attributes

Stepper container that owns orientation, step state, and panel rendering.

No attribute metadata for this slot.

Props#

Prop	Type	Default	Description
activationMode	`"manual" \| "automatic" \| undefined`	`automatic`	Whether keyboard activation happens immediately or only after confirmation.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`StepperT.Classes \| undefined`	—	—
clickable	`boolean \| undefined`	`false`	Whether steps are clickable for navigation.
defaultValue	`StepperT.Value \| undefined`	—	Default active step value for uncontrolled usage.
disabled	`boolean \| undefined`	`false`	Whether the entire stepper is disabled.
id	`string \| undefined`	—	Unique identifier for the stepper root element.
items	`StepperT.Item[] \| undefined`	—	Array of steps to display.
linear	`boolean \| undefined`	`true`	Whether to enforce linear navigation (must complete steps in order).
onChange	`((value: StepperT.Value) => void) \| undefined`	—	Callback when the active step changes.
orientation	`"horizontal" \| "vertical" \| undefined`	`horizontal`	The orientation of the stepper.
ref	`JSX.HTMLElementTags["div"] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
size	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| undefined`	—	—
style	`JSX.CSSProperties \| undefined`	—	—
styles	`StepperT.Styles \| undefined`	—	—
value	`StepperT.Value \| undefined`	—	Controlled active step value.

Items#

An individual step in the stepper.

Prop	Type	Default	Description
class	`string \| undefined`	—	Additional class name for the step item.
content	`JSX.Element`	—	Content to display when the step is active.
description	`JSX.Element`	—	Secondary description of the step.
disabled	`boolean \| undefined`	`false`	Whether the step is disabled.
icon	`IconT.Name`	`index + 1`	Icon to display in the step indicator.
title	`JSX.Element`	—	Title of the step.
value	`StepperT.Value \| undefined`	`index of the item`	Unique value for the step.