# The flow and the stepper

> The three objects you work with, and how they relate.

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

Three words are used throughout these docs. They are different things.

| Name | What it is | Where it comes from |
| --- | --- | --- |
| **Definition** | The typed description of the steps, with hooks and components bound to it. Holds no state. | `defineStepper(steps)` |
| **Flow** | One running instance: the current step, the data of every step, which steps are complete. | `useStepper()`, `Provider`, `Stepper.Root` or `create()` each create one |
| **Stepper** | What your component reads: a picture of the flow at one moment, plus the actions that change it. | Returned by `useStepper()` and `useStepperContext()` |

```tsx
const checkout = defineStepper([{ id: "shipping" }, { id: "payment" }, { id: "review" }]); // definition

function Checkout() {
  const stepper = checkout.useStepper(); // creates a flow, returns its stepper
  return <p>{stepper.current.id}</p>;
}
```

## One flat object [#one-flat-object]

Everything you read and everything you do is directly on the stepper. There
are no nested namespaces to learn.

```tsx
stepper.current; // the step being shown, with your fields
stepper.index; // its position
stepper.data; // the data of every step
stepper.next(values); // save, validate and move forward
stepper.prev(); // go back
```

Most flows ship with six members:

| Member | What it gives you |
| --- | --- |
| `current` | The step being shown. |
| `match({...})` | Exhaustive rendering by step id. |
| `next(data?)`, `prev()` | Move through the flow. |
| `isFirst`, `isLast` | What your Back and Continue buttons need. |
| `data` | What each step has saved. |

The rest (branching, snapshots, jumping to a step) is there when you need it.
The [full reference](https://stepperize.com/docs/v9/react/api/stepper) lists every member.

## Derived from one position [#derived-from-one-position]

You only express intent: go next, go back, jump to review. The stepper derives
the consequences from the flow's state, so they can never disagree.

```tsx
const flow = checkout.create(); // the same flow, without React

flow.index; // 0
flow.isFirst; // true
flow.progress; // 0

await flow.next();

flow.index; // 1
flow.current.id; // "payment"
flow.state("shipping"); // "complete"
flow.progress; // 0.5
```

## A stepper is a snapshot in time [#a-stepper-is-a-snapshot-in-time]

Each change produces a new stepper, and your component re-renders with it. The
one you already hold does not change. That is what makes it safe to compare in
selectors and effects, and it has one consequence worth knowing: after an
`await`, the stepper captured by your handler still describes the moment
before the move.

```tsx
async function onContinue() {
  const result = await stepper.next(values);

  stepper.current.id; // still the step you were on
  if (result.accepted) result.to; // where the flow went, or null if it finished
}
```

Read what happened from the result, not from the stepper in scope. The actions
themselves (`next`, `prev`, `goTo`, `setData`...) always act on the live flow,
so calling them from an old stepper is fine.

## Who owns the flow [#who-owns-the-flow]

The component that creates the flow owns it and configures it.

| You write | The flow lives |
| --- | --- |
| `checkout.useStepper(options)` | In that component. Each call is a separate flow. |
| `<checkout.Provider {...options}>` | In the provider, shared with everything below. |
| `<Stepper.Root {...options}>` | In the root, shared with everything below. |
| `checkout.create(options)` | Wherever you keep the returned object. |

Options go on the owner. Components below a `Provider` or a `Stepper.Root`
read the flow with `useStepperContext()` and cannot reconfigure it. See
[Shared state](https://stepperize.com/docs/v9/react/guides/shared-state).

Next: [the lifecycle of a move](https://stepperize.com/docs/v9/react/concepts/moves).
