Stepper

Beta

Step-by-step progress and navigation component.

Installation

npm install @xaui/native

Import

import { Stepper, StepperItem } from '@xaui/native/stepper'

Basic Usage

Minimal example showing the component with its default configuration.

import { Stepper } from '@xaui/native/stepper'

export function Example() {
  return (
    <Stepper>
      {/* children */}
    </Stepper>
  )
}

Basic Horizontal

Horizontal stepper with a controlled active step.

import { useState } from 'react'
import { Stepper, StepperItem } from '@xaui/native/stepper'
import { Typography } from '@xaui/native/typography'

export function BasicStepperExample() {
  const [activeKey, setActiveKey] = useState('details')

  return (
    <>
      <Stepper activeKey={activeKey} onStepChange={setActiveKey}>
        <StepperItem itemKey="account" title="Account" description="Create profile" />
        <StepperItem itemKey="details" title="Details" description="Personal info" />
        <StepperItem itemKey="payment" title="Payment" description="Card details" />
        <StepperItem itemKey="review" title="Review" description="Confirm" isLocked />
      </Stepper>
      <Typography variant="caption">Active: {activeKey}</Typography>
    </>
  )
}

Vertical and Line Display

Use vertical direction and control connector visibility.

import { Stepper, StepperItem } from '@xaui/native/stepper'
import { Column } from '@xaui/native/view'

export function VerticalStepperExample() {
  return (
    <Column gap={16}>
      <Stepper direction="vertical" lineDisplayMode="progress" defaultActiveKey="ship">
        <StepperItem itemKey="cart" title="Cart" />
        <StepperItem itemKey="ship" title="Shipping" />
        <StepperItem itemKey="pay" title="Payment" />
      </Stepper>

      <Stepper direction="vertical" showLines={false} defaultActiveKey="pay">
        <StepperItem itemKey="cart" title="Cart" />
        <StepperItem itemKey="ship" title="Shipping" />
        <StepperItem itemKey="pay" title="Payment" />
      </Stepper>
    </Column>
  )
}

Sizes and Theme Colors

Scale step indicators and apply semantic colors.

import { Stepper, StepperItem } from '@xaui/native/stepper'
import { Column } from '@xaui/native/view'

export function StepperSizeThemeExample() {
  return (
    <Column gap={14}>
      <Stepper size="sm" themeColor="primary" defaultActiveKey="b">
        <StepperItem itemKey="a" title="A" />
        <StepperItem itemKey="b" title="B" />
        <StepperItem itemKey="c" title="C" />
      </Stepper>

      <Stepper size="lg" themeColor="success" defaultActiveKey="b">
        <StepperItem itemKey="a" title="A" />
        <StepperItem itemKey="b" title="B" />
        <StepperItem itemKey="c" title="C" />
      </Stepper>
    </Column>
  )
}

Custom Indicator

Render indicator content from item state.

import { Stepper, StepperItem } from '@xaui/native/stepper'
import { Typography } from '@xaui/native/typography'

export function CustomIndicatorStepperExample() {
  return (
    <Stepper direction="vertical" defaultActiveKey="sync" themeColor="secondary">
      <StepperItem
        itemKey="queue"
        title="Queued"
        indicator={({ index }) => <Typography variant="caption">{index + 1}</Typography>}
      />
      <StepperItem
        itemKey="sync"
        title="Syncing"
        indicator={({ isActive, isCompleted }) => (
          <Typography variant="caption">
            {isCompleted ? 'DONE' : isActive ? 'NOW' : 'WAIT'}
          </Typography>
        )}
      />
      <StepperItem itemKey="finish" title="Finish" isLocked indicator="L" />
    </Stepper>
  )
}

Disabled States

Disable the whole stepper or individual items.

import { Stepper, StepperItem } from '@xaui/native/stepper'
import { Column } from '@xaui/native/view'

export function DisabledStepperExample() {
  return (
    <Column gap={16}>
      <Stepper isDisabled defaultActiveKey="a">
        <StepperItem itemKey="a" title="Step A" />
        <StepperItem itemKey="b" title="Step B" />
      </Stepper>

      <Stepper defaultActiveKey="a">
        <StepperItem itemKey="a" title="Step A" />
        <StepperItem itemKey="b" title="Step B" isDisabled />
        <StepperItem itemKey="c" title="Step C" isLocked />
      </Stepper>
    </Column>
  )
}