# Steps and ids

> Model each step with a stable id, and keep your own data on it.

Source: https://stepperize.com/docs/v9/react/concepts/steps

A step is a plain object. Only `id` is required; everything else belongs to
your app.

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

export const checkout = defineStepper([
  { id: "shipping", title: "Shipping", icon: "truck" },
  { id: "payment", title: "Payment", icon: "card" },
  { id: "review", title: "Review", icon: "check" },
]);
```

The definition is the contract for the whole flow. The hook, `match`, the data
of each step, the `next` map and the primitives all use these same ids, and
TypeScript knows them as the union `"shipping" | "payment" | "review"`.

## Step ids [#step-ids]

Ids are what you save, put in the URL and branch on. Pick ones that describe
the business step, not the current label or position.

| Good | Avoid | Why |
| --- | --- | --- |
| `"shipping"` | `"Step 1"` | Reordering steps would change its meaning. |
| `"payment"` | `"Pay now"` | Copy changes; ids should not. |
| `"review"` | `"confirm-2026"` | Generated ids cannot be typed or bookmarked. |

Ids must be unique. An empty list or a repeated id throws
[SZ103](https://stepperize.com/docs/v9/core/errors#sz103) when the definition is created.

## Your own fields [#your-own-fields]

Any other field stays on the step, fully typed, wherever Stepperize hands you a
step: `stepper.current`, `stepper.steps`, the `match` handlers and the
`Stepper.List` function.

```tsx
function Header() {
  const stepper = checkout.useStepperContext();
  return (
    <h2>
      <Icon name={stepper.current.icon} /> {stepper.current.title}
    </h2>
  );
}
```

Two fields have a meaning for the library:

| Field | Used for |
| --- | --- |
| `schema` | Types the step's data, and `next()` validates against it. See [Validation](https://stepperize.com/docs/v9/react/guides/validation). |
| `title`, `description` | Shown by `Stepper.Title` and `Stepper.Description`. A string `title` is also what screen readers hear when the step changes. |

Everything else (`icon`, `optional`, `estimatedMinutes`, a component) is yours.

## Define once, at module scope [#define-once-at-module-scope]

A definition holds no state. It is the description of the flow, plus the hooks
and components bound to it. Create it once, outside your components, and
import it where you need it.

```tsx
// Wrong: a new definition, and a new empty flow, on every render.
function Checkout() {
  const checkout = defineStepper([{ id: "shipping" }, { id: "payment" }]);
  const stepper = checkout.useStepper();
}
```

Every `useStepper()` call or `Provider` of the same definition is an
independent flow, so one definition can back several flows on a page.

## Keep ids literal [#keep-ids-literal]

Ids stay literal when the array is written inline. If you build the array
first, add `as const`, or the ids widen to `string` and you lose the checks.

```tsx
// Ids are string: nothing is checked.
const steps = [{ id: "account" }, { id: "profile" }];
const loose = defineStepper(steps);

// Ids are "account" | "profile".
const inline = defineStepper([{ id: "account" }, { id: "profile" }]);

const list = [{ id: "account" }, { id: "profile" }] as const;
const pinned = defineStepper(list);
```

## Fields that only some steps have [#fields-that-only-some-steps-have]

`stepper.current` is the union of all your steps. A field that exists on some
steps only is not available until you know which step you are on. `match`
narrows for you:

```tsx
const signup = defineStepper([
  { id: "account", title: "Account", help: "We never share your email." },
  { id: "done", title: "All set" },
]);

function Body() {
  const stepper = signup.useStepperContext();
  return stepper.match({
    account: (step) => <p>{step.help}</p>,
    done: (step) => <p>{step.title}</p>,
  });
}
```

Comparing `stepper.current.id` narrows it too.

Next: [the flow and the stepper](https://stepperize.com/docs/v9/react/concepts/stepper), the objects
you work with at runtime.
