Stepper

01Preview

Change the controls to try every supported combination. The preview renders the real component and the code updates with it.

import { Stepper, type StepperStep } from '@nuton/ui'

const steps: StepperStep[] = [
  { title: 'Your goal', description: 'What brings you here?' },
  { title: 'Your learning style', description: 'How should we explain it?' },
  { title: 'Your tutor', description: 'Choose how your tutor talks with you.' },
  { title: 'Invite a friend', description: 'Study together in a space.', optional: true },
]

<Stepper
  steps={steps}
  activeStep={1}
  onStepSelect={setActiveStep}
  aria-label="Set up your studio"
/>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. The check and cross come from @remixicon/react.

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

03Usage

import { Stepper } from '@nuton/ui'

const steps = [
  { title: 'Your goal' },
  { title: 'Your learning style' },
  { title: 'Your tutor' },
]

export function SetupSteps({ step }: { step: number }) {
  return <Stepper steps={steps} activeStep={step} aria-label="Set up your studio" />
}

• activeStep is 0-based. Steps before it are complete, the step at it is current, later ones are upcoming. -1 means nothing has started; a value past the end marks every step complete.
• Set status on a step only to override that, usually 'error' for a step that failed.
• Give the list a name with aria-label (default “Steps”) or aria-labelledby.
• Pass onStepSelect to let people go back: completed steps become buttons. Later steps never are.
• Use 3 to 5 steps. For longer flows, use variant="compact" or a Progress bar.

04Variants and sizes

The default variant lists every step, horizontally or vertically. Compact and dots save space on phones and in modal footers.

Horizontal

<Stepper
  steps={[
    { title: 'Your goal', description: 'What brings you here?' },
    { title: 'Your learning style', description: 'How should we explain it?' },
    { title: 'Your tutor', description: 'Choose how your tutor talks with you.' },
  ]}
  activeStep={1}
  aria-label="Set up your studio"
/>

Steps share the width and connectors fill the space between them. When the stepper is narrower than 560px, only the current step shows its text, as in the live onboarding; the other names stay available to screen readers.

Vertical

<Stepper orientation="vertical" steps={steps} activeStep={1} aria-label="Set up your studio" />

Numbers or icons

<Stepper
  indicator="icon"
  steps={[
    { title: 'Your goal', icon: <RiCompass3Line /> },
    { title: 'Your learning style', icon: <RiLightbulbLine /> },
    { title: 'Your tutor', icon: <RiUser3Line /> },
  ]}
  activeStep={1}
  aria-label="Set up your studio"
/>

Complete steps always show a check and error steps a cross, whatever the indicator. Icons are decorative.

Compact

<Stepper variant="compact" steps={steps} activeStep={1} />

“Step 2 of 3”, the current title and a Progress bar (code-only, for phones). It renders a named progressbar rather than a list; the bar turns red on an error and green when every step is done.

Dots

<Stepper variant="dots" steps={steps} activeStep={0} aria-label="Set up your studio" />
<Stepper variant="dots" dotSize="xs" steps={steps} activeStep={1} aria-label="Set up your studio" />

Figma Stepper Dot [1.1], used in the Modal footer. Step names are visually hidden but still read as a list. Dots are never buttons (too small to press).

Dimensions

Taken from the component CSS. Dots match Figma 365:20271; the rest is code-only (live onboarding uses a 21px indicator).

05States and interactions

Each step is complete, current, upcoming or error. Any step can also be optional. The state is in hidden text as well as colour.

Tokens

06Composition examples

Onboarding

The live setup dialog: Back and Continue move between steps, and completed steps are buttons. After each move, focus goes to the step heading so the change is announced.

<Stepper steps={steps} activeStep={step} onStepSelect={go} aria-label="Set up your studio" />
<h3 ref={headingRef} tabIndex={-1}>{steps[step].description}</h3>
<Button size="sm" appearance="stroke" disabled={step === 0} onClick={() => go(step - 1)}>Back</Button>
<Button size="sm" onClick={() => go(step + 1)}>Continue</Button>

Course generation

A vertical stepper that advances on its own. The stepper doesn't announce changes, so a role="status" line says what is happening.

const phases = ['Reviewing your sources', 'Mapping the topic', 'Defining the course architecture', 'Sequencing chapters', 'Drafting your first lesson']

<Stepper orientation="vertical" steps={phases.map((title) => ({ title }))} activeStep={phase} aria-label="Generating your course" />
<p role="status">{phase < phases.length ? `${phases[phase]}…` : 'Your course is ready.'}</p>

Phones and translation

On small screens use the compact variant. Every string can be replaced through labels; stepOf is a function so word order can change.

<Stepper
  variant="compact"
  steps={steps}
  activeStep={1}
  labels={{ stepOf: (step, total) => `Étape ${step} sur ${total}` }}
/>

07API reference

Stepper props

StepperStep

Also exported: getStepStatus(step, index, activeStep), STEPPER_LABELS and the types StepperStatus, StepperLabels.

Styling hooks

The root is .nu-stepper with data-variant, data-orientation, data-indicator and data-dot-size. Each li.nu-stepper__step has data-status. Override the tokens in Tokens.

Accessibility

You must: name the stepper; keep step titles short and unique; announce progress or move focus when the step changes; describe errors in words.

Figma mapping

The full list, compact view, states and connectors have no Figma source (C3); they follow the live onboarding steps.

08Guidelines and related components

Do and don't

Common mistakes

• Treating activeStep as 1-based. The first step is 0.
• Making future steps clickable with clickable: true before earlier steps are valid.
• Two steppers on one page with the same default name “Steps”. Give each an aria-label.
• Changing the step without moving focus or announcing it.

Related components

• ProgressThe bar inside the compact variant.
• ModalModal footers with the Figma stepper dots.
• ButtonBack and Continue actions.
• AccordionIndependent sections instead of ordered steps.