Primitives

The Stepper object returned by defineStepper provides a set of primitive components that are type-safe and bound to your step definitions. They handle ARIA attributes, keyboard navigation, and data attributes automatically; stepper state is provided by Scoped or Stepper.Root.

Overview

import * as React from "react"
import { defineStepper } from "@stepperize/react"

const { Stepper } = defineStepper(
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "confirmation", title: "Confirmation" }
);

function CheckoutStepper() {
  return (
    <Stepper.Root>
      {({ stepper }) => (
        <>
          <Stepper.List>
            {stepper.state.all.map((step) => (
              <Stepper.Item key={step.id} step={step.id}>
                <Stepper.Trigger>
                  <Stepper.Indicator />
                  <Stepper.Title>{step.title}</Stepper.Title>
                </Stepper.Trigger>
                <Stepper.Separator />
              </Stepper.Item>
            ))}
          </Stepper.List>

          <Stepper.Content step="shipping">
            Shipping form here
          </Stepper.Content>
          <Stepper.Content step="payment">
            Payment form here
          </Stepper.Content>
          <Stepper.Content step="confirmation">
            Confirmation here
          </Stepper.Content>

          <Stepper.Actions>
            <Stepper.Prev>Previous</Stepper.Prev>
            <Stepper.Next>Next</Stepper.Next>
          </Stepper.Actions>
        </>
      )}
    </Stepper.Root>
  );
}

Component Hierarchy

Stepper.Root
├── Stepper.List
│   └── Stepper.Item (for each step)
│       ├── Stepper.Trigger
│       │   ├── Stepper.Indicator
│       │   ├── Stepper.Title
│       │   └── Stepper.Description
│       └── Stepper.Separator
├── Stepper.Content (for each step)
└── Stepper.Actions
    ├── Stepper.Prev
    └── Stepper.Next

Accessibility

The primitives implement the WAI-ARIA Tabs pattern so the stepper is announced and operable with keyboard and assistive technologies. The step list is exposed as a tablist, each step trigger as a tab, and each step content as a tabpanel. Stepper semantics are added with aria-current="step" on the active tab.

Roles and attributes by component

Keyboard interaction

When focus is on a tab (trigger) inside the list:

The tabpanel (content) has tabIndex={0} so that when it has no focusable children, users can still Tab into it and then Tab out to the next region.

References

• WAI-ARIA Authoring Practices Guide (APG) – Tabs
• ARIA: tab role (MDN)
• ARIA: tablist role (MDN)
• ARIA: tabpanel role (MDN)

Accessing step data

You can get step data in three ways when using primitives:

Render prop on Stepper.Root

The root accepts a function {({ stepper }) => (...)} that receives the full stepper instance. Use it when you need current step, navigation, flow, lookup, and metadata in the same place you render the list and content:

<Stepper.Root>
  {({ stepper }) => (
    <>
      <div>Current: {stepper.state.current.data.title}</div>
      <Stepper.List>...</Stepper.List>
      <Stepper.Content step="shipping">...</Stepper.Content>
      <Stepper.Actions>
        <Stepper.Prev />
        <Stepper.Next>{stepper.state.isLast ? "Finish" : "Next"}</Stepper.Next>
      </Stepper.Actions>
    </>
  )}
</Stepper.Root>

useStepper() — global stepper in any child

Any component inside Stepper.Root can call useStepper() (from your defineStepper result) to access the full stepper: current step, next(), prev(), goTo(), when(), switch(), etc. Use it for content panels, navigation logic, or any component that needs to know "where we are" and control the flow.

const { Stepper, useStepper } = defineStepper(/* step1, step2, ... */);

function ShippingForm() {
  const stepper = useStepper();
  return (
    <Stepper.Content step="shipping">
      <p>Step: {stepper.state.current.data.title}</p>
      <button onClick={() => stepper.navigation.next()}>Continue</button>
    </Stepper.Content>
  );
}

useStepItemContext() — this item's step

useStepItemContext() returns the step data, index, status, and metadata for the Stepper.Item that wraps the component that calls the hook. Use it when you need to read or style based on "this step" (e.g. this item's status or index) without passing the step id as a prop.

Import: useStepItemContext is exported from @stepperize/react/primitives (not from the main @stepperize/react entry).

import { useStepItemContext } from "@stepperize/react/primitives";

Same type as useStepper().state.current, different value:

• useStepper().state.current — The active step (the one the user is on). One value for the whole stepper; it changes when you navigate.
• useStepItemContext() — This item's step. Each Stepper.Item has its own step; the hook returns that step's data and its computed status (active/success/inactive). For example, inside <Stepper.Item step="payment"> you get payment's data and payment's status (e.g. "inactive" if the user is still on shipping).

When to use: Inside custom trigger wrappers, indicators, titles, or any component rendered inside Stepper.Item that needs this step's data, index, status, or metadata without receiving the step id from the parent.

When not to use: For global stepper state (which step is active, navigation, flow) use useStepper(). For content panels use Stepper.Content or stepper.flow.switch(); those live outside items.

Requirement: The hook must be called from a component that is a descendant of Stepper.Item. Otherwise it throws. For components outside items, use useStepper() instead.

Return value

Example: custom indicator with step number

Use item.index to show a numeric indicator (1, 2, 3) without passing the step id:

import * as React from "react";
import { defineStepper } from "@stepperize/react";
import { useStepItemContext } from "@stepperize/react/primitives";

const { Stepper } = defineStepper(
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" }
);

function StepNumber() {
  const item = useStepItemContext();
  return <span>{item.index + 1}</span>;
}

function MyStepper() {
  return (
    <Stepper.Root>
      {({ stepper }) => (
        <Stepper.List>
          {stepper.state.all.map((step) => (
            <Stepper.Item key={step.id} step={step.id}>
              <Stepper.Trigger>
                <Stepper.Indicator>
                  <StepNumber />
                </Stepper.Indicator>
                <Stepper.Title>{step.title}</Stepper.Title>
              </Stepper.Trigger>
              <Stepper.Separator />
            </Stepper.Item>
          ))}
        </Stepper.List>
      )}
    </Stepper.Root>
  );
}

Example: style trigger by status

Use item.status to change the trigger's appearance (e.g. active vs inactive) without comparing step ids yourself:

import * as React from "react";
import { defineStepper } from "@stepperize/react";
import { useStepItemContext } from "@stepperize/react/primitives";

const { Stepper } = defineStepper(
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" }
);

function CustomTrigger({ children }: { children: React.ReactNode }) {
  const item = useStepItemContext();
  const isActive = item.status === "active";

  return (
    <Stepper.Trigger
      render={(props) => (
        <button
          type="button"
          {...props}
          className={isActive ? "border-blue-500 bg-blue-50" : "border-gray-300 bg-white"}
        >
          {children}
        </button>
      )}
    >
      {children}
    </Stepper.Trigger>
  );
}

// Use inside Item
// <Stepper.Item step="shipping">
//   <CustomTrigger>
//     <Stepper.Indicator />
//     <Stepper.Title>Shipping</Stepper.Title>
//   </CustomTrigger>
// </Stepper.Item>

Example: show icon only when step is completed

Use item.status === "success" to display a checkmark or icon for past steps:

const item = useStepItemContext();
const isCompleted = item.status === "success";

return (
  <Stepper.Trigger render={(props) => (
    <button {...props}>
      {isCompleted ? <CheckIcon /> : <Stepper.Indicator />}
      <Stepper.Title>{item.data.title}</Stepper.Title>
    </button>
  )}>
    ...
  </Stepper.Trigger>
);

Summary

Stepper.Root

Container component that provides context for all primitives. Internally uses Scoped to manage stepper state.

<Stepper.Root orientation="horizontal">
  {({ stepper }) => (
    <div>Current: {stepper.state.current.data.title}</div>
  )}
</Stepper.Root>

Props

Data Attributes

Stepper.List

Ordered list container for step items. Renders as <ol> by default.

<Stepper.List>
  {stepper.state.all.map((step) => (
    <Stepper.Item key={step.id} step={step.id}>
      {/* ... */}
    </Stepper.Item>
  ))}
</Stepper.List>

Props

Data Attributes

Accessibility

• role="tablist", aria-orientation from orientation prop
• Keyboard: Arrow keys (prev/next step), Home (first), End (last) — see Accessibility (ARIA)

Stepper.Item

Wrapper for a single step. Provides context for nested primitives.

<Stepper.Item step="shipping">
  <Stepper.Trigger>
    <Stepper.Indicator />
    <Stepper.Title>Shipping</Stepper.Title>
  </Stepper.Trigger>
  <Stepper.Separator />
</Stepper.Item>

Props

Data Attributes

Stepper.Trigger

Clickable button to navigate to a step. Must be used within Stepper.Item.

<Stepper.Item step="step-1">
  <Stepper.Trigger onClick={() => console.log("Custom click")}>
    <Stepper.Indicator />
    <Stepper.Title>Step 1</Stepper.Title>
  </Stepper.Trigger>
</Stepper.Item>

Props

Data Attributes

Same as Stepper.Item.

Accessibility

• role="tab", id="step-{stepId}", aria-controls, aria-current="step" (when active), aria-selected, aria-posinset, aria-setsize
• Roving tabindex: only the active tab has tabIndex={0}; inactive tabs have tabIndex={-1}
• Keyboard: Arrow keys, Home, End — handled by Stepper.List; see Accessibility (ARIA)

Stepper.Indicator

Visual indicator for the step (e.g. number or icon). Must be used within Stepper.Item. Renders whatever you pass as children or via render; there is no built-in default content.

{/* Custom: show step index via useStepItemContext or children */}
<Stepper.Indicator>{item.index + 1}</Stepper.Indicator>

{/* Custom: show icon */}
<Stepper.Indicator>
  <CheckIcon />
</Stepper.Indicator>

Props

Data Attributes

Same as Stepper.Item.

Accessibility

• aria-hidden="true" (indicator is decorative, the title provides the accessible name)

Stepper.Title

Renders the step title. Can be used within or outside Stepper.Item.

<Stepper.Item step="shipping">
  <Stepper.Trigger>
    <Stepper.Title>Shipping Address</Stepper.Title>
  </Stepper.Trigger>
</Stepper.Item>

Props

Data Attributes

Same as Stepper.Item when used inside an Item.

Stepper.Description

Renders the step description. Can be used within or outside Stepper.Item.

<Stepper.Item step="shipping">
  <Stepper.Trigger>
    <Stepper.Title>Shipping</Stepper.Title>
    <Stepper.Description>Enter your shipping address</Stepper.Description>
  </Stepper.Trigger>
</Stepper.Item>

Props

Data Attributes

Same as Stepper.Item when used inside an Item.

Stepper.Separator

Visual separator line between steps. Renders between items; hide the last separator in your layout (e.g. by rendering it only when not the last item in the list) or style it via CSS if needed.

<Stepper.List>
  {stepper.state.all.map((step, index) => (
    <React.Fragment key={step.id}>
      <Stepper.Item step={step.id}>
        <Stepper.Trigger>...</Stepper.Trigger>
      </Stepper.Item>
      {index < stepper.state.all.length - 1 && <Stepper.Separator />}
    </React.Fragment>
  ))}
</Stepper.List>

Props

Data Attributes

Accessibility

• aria-hidden="true", tabIndex={-1} — decorative; not in tab order and hidden from assistive tech

Stepper.Content

Panel that displays content for a specific step. Hidden when that step is not the current step.

<Stepper.Content step="shipping">
  <ShippingForm />
</Stepper.Content>

<Stepper.Content step="payment">
  <PaymentForm />
</Stepper.Content>

<Stepper.Content step="confirmation">
  <ConfirmationView />
</Stepper.Content>

Props

Data Attributes

The component does not set data-status, data-step, data-index, or data-orientation by default; pass them via props if needed.

Accessibility

• role="tabpanel", id="step-panel-{stepId}", aria-labelledby linked to the trigger, tabIndex={0} so the panel is in the tab order when it has no focusable children
• Only the panel for the current step is rendered; inactive steps do not render content

Stepper.Actions

Container for navigation buttons. Provides semantic grouping.

<Stepper.Actions>
  <Stepper.Prev>Previous</Stepper.Prev>
  <Stepper.Next>Next</Stepper.Next>
</Stepper.Actions>

Props

Data Attributes

Accessibility

• No default role or aria-label; add role="group" and aria-label via props if you want the actions region announced.

Stepper.Prev

Button to navigate to the previous step. Automatically disabled on first step.

{/* Default behavior */}
<Stepper.Prev>Previous</Stepper.Prev>

{/* Custom disabled behavior */}
<Stepper.Prev>Back</Stepper.Prev>

{/* Custom click handler */}
<Stepper.Prev onClick={() => {
  console.log("Going back");
  stepper.navigation.prev();
}}>
  Previous
</Stepper.Prev>

Props

Data Attributes

Accessibility

• disabled and aria-disabled when on the first step; provide visible label via children (e.g. "Previous", "Back")

Stepper.Next

Button to navigate to the next step. Automatically disabled on last step.

{/* Default behavior */}
<Stepper.Next>Next</Stepper.Next>

{/* Dynamic label */}
<Stepper.Next>
  {stepper.state.isLast ? "Finish" : "Next"}
</Stepper.Next>

{/* Custom click with validation */}
<Stepper.Next onClick={async () => {
  const isValid = await validateCurrentStep();
  if (isValid) {
    stepper.navigation.next();
  }
}}>
  Continue
</Stepper.Next>

Props

Data Attributes

Accessibility

• disabled and aria-disabled when on the last step; provide visible label via children (e.g. "Next", "Finish")

Custom Rendering

All primitives support the render prop for full control over the rendered element:

<Stepper.Trigger
  render={(props) => (
    <button {...props} className="my-custom-trigger">
      Custom Trigger
    </button>
  )}
/>

The render function receives all props including data attributes, event handlers, and ARIA attributes. Spread them onto your element (e.g. <button {...props} />) so ARIA and keyboard behavior are preserved.

Styling with Data Attributes

Use data attributes for CSS styling. Step status is one of "active", "success", or "inactive":

/* Active step (current) */
[data-status="active"] {
  color: blue;
}

/* Completed step (past) */
[data-status="success"] {
  color: green;
}

/* Inactive step (future) */
[data-status="inactive"] {
  color: gray;
}

/* Disabled (e.g. Prev/Next when at first/last step) */
[data-disabled] {
  opacity: 0.5;
  cursor: not-allowed;
}

/* Horizontal layout */
[data-orientation="horizontal"] {
  display: flex;
  flex-direction: row;
}

/* Vertical layout */
[data-orientation="vertical"] {
  display: flex;
  flex-direction: column;
}

Complete Example

import * as React from "react"
import { defineStepper } from "@stepperize/react"

const { Stepper, useStepper } = defineStepper(
  { id: "account", title: "Account", description: "Create your account" },
  { id: "profile", title: "Profile", description: "Set up your profile" },
  { id: "complete", title: "Complete", description: "All done!" }
);

function OnboardingStepper() {
  return (
    <Stepper.Root orientation="horizontal">
      {({ stepper }) => (
        <div className="stepper-container">
          {/* Step list */}
          <Stepper.List className="stepper-list">
            {stepper.state.all.map((step) => (
              <Stepper.Item
                key={step.id}
                step={step.id}
                className="stepper-item"
              >
                <Stepper.Trigger className="stepper-trigger">
                  <Stepper.Indicator className="stepper-indicator" />
                  <div className="stepper-text">
                    <Stepper.Title className="stepper-title">
                      {step.title}
                    </Stepper.Title>
                    <Stepper.Description className="stepper-description">
                      {step.description}
                    </Stepper.Description>
                  </div>
                </Stepper.Trigger>
                <Stepper.Separator className="stepper-separator" />
              </Stepper.Item>
            ))}
          </Stepper.List>

          {/* Step content */}
          <div className="stepper-content-container">
            <Stepper.Content step="account">
              <h2>Create Account</h2>
              <p>Enter your email and password</p>
            </Stepper.Content>

            <Stepper.Content step="profile">
              <h2>Set Up Profile</h2>
              <p>Tell us about yourself</p>
            </Stepper.Content>

            <Stepper.Content step="complete">
              <h2>All Done!</h2>
              <p>Your account is ready</p>
            </Stepper.Content>
          </div>

          {/* Navigation */}
          <Stepper.Actions className="stepper-actions">
            <Stepper.Prev className="stepper-prev">
              Previous
            </Stepper.Prev>
            <Stepper.Next className="stepper-next">
              {stepper.state.isLast ? "Finish" : "Next"}
            </Stepper.Next>
          </Stepper.Actions>
        </div>
      )}
    </Stepper.Root>
  );
}