Steps

Preview

Installation

pnpm add @oshon-ai/components @oshon-ai/tokens @oshon-ai/primitives

pnpm dlx @oshon-ai/cli add steps

Wire the tokens into your Tailwind v4 stylesheet:

/* app/globals.css */
@import 'tailwindcss';
@import '@oshon-ai/tokens/css';
@import '@oshon-ai/tokens/tailwind';

New here? Walk through the full setup — prereqs, theming, your first render.

Usage

Import the component and render it. Every component supports the standard tier, size, and disabled props where applicable.

'use client';
import { Steps } from '@oshon-ai/components';

export default function Example() {
  return <Steps />;
}

<div style={{ ...col, gap: '2rem', width: '100%', maxWidth: '760px' }}>
      <section style={card}>
        <h3 style={heading}>Progression: completed, active, and upcoming</h3>
        <Steps steps={FIVE_STEPS} current={2} />
        <div style={caption}>
          Steps before the current one are completed, with a solid teal
          connector. The current step is active. Upcoming steps are incomplete,
          with a dashed gray connector.
        </div>
      </section>

      <section style={card}>
        <h3 style={heading}>Error state</h3>
        <Steps
          steps={[
            { label: 'Account' },
            { label: 'Profile', state: 'error' },
            { label: 'Plan' },
            { label: 'Payment' },
            { label: 'Confirm' },
          ]}
          current={1}
        />
        <div style={caption}>
          A per-step <code>state: &apos;error&apos;</code> override marks one step
          red without moving the overall progress position.
        </div>
      </section>
    </div>

<WizardDemo />

<SkipAheadDemo />

<div style={{ ...col, width: '100%', maxWidth: '760px' }}>
      <Steps
        steps={[
          { label: 'Upload' },
          { label: 'Validate', state: 'error' },
          { label: 'Publish' },
        ]}
        current={1}
      />
      <div style={caption}>
        After a validation failure, mark the broken step
        <code>{` state: 'error' `}</code>
        and leave <code>current</code> on it. The user sees both the
        failure cue and the next-action affordance in one rail.
      </div>
    </div>

<div style={{ ...col, width: '100%', maxWidth: '480px' }}>
      <Steps
        orientation="vertical"
        steps={[
          {
            label: 'Connect a workspace',
            description: 'Link your Slack or Teams account to start syncing',
          },
          {
            label: 'Invite teammates',
            description: 'Send up to 10 invites — they keep their seats',
          },
          {
            label: 'Pick a plan',
            description: 'Free for the first 14 days, no card required',
          },
          {
            label: 'Launch',
          },
        ]}
        current={1}
      />
    </div>

<div style={{ ...col, gap: '2rem' }}>
      {SIZES.map((size) => (
        <section key={size} style={card}>
          <h3 style={heading}>size={size}</h3>
          <Steps
            size={size}
            steps={[
              { label: 'Account' },
              { label: 'Plan' },
              { label: 'Confirm' },
            ]}
            current={1}
          />
        </section>
      ))}
    </div>

API

Every prop is documented here directly from the component's TypeScript interface. Inherited DOM attributes (aria-*, onClick, style, etc.) work as usual but are omitted from this table.

Styling

Three layers of customization, in order of escape-hatch strength: className overrides → data-attribute targeting → CSS custom properties.

Passing Tailwind classes

Every Oshon component accepts a className prop merged AFTER the component's default classes. Use it to override spacing, color, or size without forking the component.

<Steps
  className="ring-2 ring-offset-2 ring-blue-500"
/>

Data attributes

Oshon components expose their internal state as data-oshon-* attributes so you can target them from CSS without coupling to internal class names. The most common attributes are listed below — see the component's source for the full set.

/* Target the secondary tier specifically */
[data-oshon-tier="secondary"] {
  --oshon-color-primary-700: var(--my-brand-color);
}

Interactive states

Every interactive component supports the standard CSS pseudo- classes plus Tailwind's state variants. Focus rings always use :focus-visible so keyboard users see them but mouse users don't.

• :hover / hover:* — pointer hover
• :focus-visible / focus-visible:* — keyboard focus
• :active / active:* — pressed
• :disabled / disabled:* — set via the disabled prop

Anatomy

The named regions a consumer composes when rendering this component. Each is documented separately so you can target keyboard nav, ARIA labels, and slot props with precision.

Keyboard

Accessibility

Every Oshon component ships axe-clean. We test in CI on every PR and publish the audit log per component.

WCAG level

2.2 AA

Screen readers tested

VoiceOver (macOS), NVDA (Windows)

Last axe audit

2026-04-28

Do / Don't

<Steps
  steps={[
    { label: 'Account' },
    { label: 'Profile' },
    { label: 'Confirm' },
  ]}
  current={1}
/>

<Steps
  steps={steps}
  current={current}
  onStepClick={(idx) => setCurrent(idx)}
/>

<Steps
  steps={[
    { label: 'Upload' },
    { label: 'Validate', state: 'error' },
    { label: 'Publish' },
  ]}
  current={1}
/>

<Steps
  orientation="vertical"
  steps={[
    { label: 'Plan', description: 'Pick a template' },
    { label: 'Build', description: 'Configure your settings' },
    { label: 'Ship' },
  ]}
  current={1}
/>

<Steps slotClassName={{ number: 'border-blue-700 text-blue-700' }} ...

<Steps allowSkipAhead onStepClick={...} ...

<Steps steps={[{label:'Home'},{label:'Pricing'}]} ...

<Steps steps={[{number: 1}, {number: 2}]} ...

Related

• Tabs
• ProgressIndicator
• Banner

Design rationale

Numbered-circle stepper, not a checkmark-only progress bar — the Figma authoring set (4 states × 2 styles) treats the step number as the primary affordance and the trailing check / error glyph as a secondary cue, satisfying WCAG SC 1.4.1 Use of Color via dual-channel feedback (number color + outline weight + glyph). Connector tone derives from the PRECEDING step (solid teal after completed; dashed gray everywhere else) so the rail reads as a left-to-right "fill-up" without an explicit progress bar layered behind it. Min 3 / Max 8 steps and the "label required" rule come from Figma frame 8617:1508 and are surfaced as TS types and a11y guidance rather than runtime asserts (the visual layer treats them as guidance the consumer can override). Default forward-navigation block matches the Figma annotation; `allowSkipAhead` is the explicit escape hatch.