# defineStepper

> Reference the API for defining typed flows.

Source: https://stepperize.com/docs/v8/api/react/define-stepper

Creates one typed flow.

```tsx
import { defineStepper } from "@stepperize/react";

const checkout = defineStepper(
  [
    { id: "shipping", title: "Shipping" },
    { id: "payment", title: "Payment" },
    { id: "review", title: "Review" },
  ],
  {
    defaultStep: "shipping",
    linear: true,
  },
);
```

Use one definition per flow: checkout, onboarding, survey, setup wizard.

The definition is static. It does not create React state until you call `useStepper`, render `Provider`, or render `Stepper.Root`.

## Parameters [#parameters]

| Parameter | Description |
| --- | --- |
| `steps` | Ordered step objects. Must contain at least one step, and each step needs a unique `id`; every other field is yours. |
| `options.defaultStep` | Initial step id. Defaults to the first step. |
| `options.defaultData` | Initial flow data. |
| `options.defaultCompleted` | Initial completed step ids. |
| `options.linear` | `false` by default. Set `true` to restrict `goTo`, triggers and list keyboard navigation to adjacent/previous steps. |

Definition options become defaults for every instance created from this
definition. Lifecycle callbacks (`beforeStepChange`, `onStepChange`) are
instance-only — pass them to `useStepper`, `Provider`, or `Stepper.Root`.

Duplicate literal ids are caught by TypeScript when the step list is a literal
tuple. Stepperize also validates ids at runtime, so dynamic or widened step
arrays still fail early with a clear error.

## Returns [#returns]

| Property | Description |
| --- | --- |
| `steps` | Original steps in order. |
| `useStepper(options?)` | Creates an independent local instance. |
| `useStepperContext(selector?, isEqual?)` | Consumes the nearest matching shared instance. |
| `Provider` | Context provider for one shared instance. |
| `Stepper` | Bound unstyled primitives. |
| `get(id)` | Pure step access by id. |
| `at(index)` | Pure step access by index. |
| `parseStep(value)` | Narrow an arbitrary value to a known step id, or `undefined`. |
| `validate(id, value)` | Validate an arbitrary value against a step's schema ([Standard Schema](https://standardschema.dev)). Schemaless steps always succeed. |

## Local instance [#local-instance]

```tsx
function Checkout() {
  const stepper = checkout.useStepper();
  return <h2>{stepper.current.title}</h2>;
}
```

## Shared instance [#shared-instance]

```tsx
function Page() {
  return (
    <checkout.Provider defaultStep="shipping">
      <CurrentTitle />
      <Actions />
    </checkout.Provider>
  );
}

function CurrentTitle() {
  const stepper = checkout.useStepperContext();
  return <h2>{stepper.current.title}</h2>;
}
```

## Step access without state [#step-access-without-state]

```tsx
const first = checkout.at(0);
const payment = checkout.get("payment");
```

Use these in static config, tests, or setup code. Use instance step access helpers inside running UI.

## Choosing defaults [#choosing-defaults]

```tsx
const checkout = defineStepper(steps, {
  defaultStep: "shipping",
  defaultData: {
    shipping: savedShippingDraft,
  },
  defaultCompleted: ["shipping"],
  linear: true,
});
```

Use definition defaults for the normal behavior of the flow. Use `useStepper(options)`, `Provider` props, or `Stepper.Root` props for a specific screen or controlled integration.

## Common mistakes [#common-mistakes]

| Mistake | Fix |
| --- | --- |
| Defining steps inside a component on every render | Move static definitions outside the component. |
| Passing an empty step array | Define at least one step. `defineStepper` throws early for empty arrays. |
| Reusing a step id | Give every step a unique id. Literal duplicates are type errors when possible; runtime validation catches the rest. |
| Using labels as ids | Use stable ids like `"shipping"` and keep labels in `title`. |
| Expecting `defaultStep` to control state after mount | Use controlled `step` / `onStepChange` for external state. |
| Marking all previous steps complete automatically | Use `setComplete(id)` when your app accepts a step. |

Keep the definition at module scope and treat the step array and its ids as immutable. Static indexes are cached per definition; mutating steps after definition is unsupported.

## Lightweight entry [#lightweight-entry]

`defineStepper` from `@stepperize/react/headless` accepts the same arguments and returns the same state API, excluding the `Stepper` UI primitives. Import its `StepperDefinition` type from the same entry. The main entry also exports this narrower type as `HeadlessStepperDefinition`.

Choose it for custom markup or React Native. See [bundle size and usage](https://stepperize.com/docs/v8/guides/performance#smaller-bundles-with-your-own-ui).
