# Stepper

> What useStepper and useStepperContext return.

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

A stepper is a picture of the flow at one moment, plus the actions that change
it. Every change produces a new stepper; the one you hold does not change. See
[The flow and the stepper](https://stepperize.com/docs/v9/react/concepts/stepper).

## State [#state]

| Property | Type | Description |
| --- | --- | --- |
| `steps` | `Step[]` | The steps of the definition. |
| `current` | `Step` | The step being shown, with all its fields. |
| `index` | `number` | Position of `current` in `steps`. |
| `isFirst` | `boolean` | `current` is the first step. |
| `isLast` | `boolean` | `next()` finishes the flow. See [Branching](https://stepperize.com/docs/v9/react/guides/branching#islast). |
| `progress` | `number` | Position of `current` in `steps`, from `0` to `1`. |
| `data` | `object` | The data of every step, by id, as it was typed: drafts included. Typed by each step's schema input. |
| `output` | `object` | What the schema of each complete step produced, by id: transforms and defaults applied. Typed by each step's schema output. See [Draft data and validated output](https://stepperize.com/docs/v9/react/guides/validation#draft-data-and-validated-output). |
| `isPending` | `boolean` | An async schema, guard or `onFinish` is running. |
| `isFinished` | `boolean` | `next()` completed a final step and `onFinish` settled. `false` again as soon as the flow changes. See [Finishing](https://stepperize.com/docs/v9/react/guides/navigation#finish-the-flow). |

## Queries [#queries]

| Method | Returns | Description |
| --- | --- | --- |
| `state(id)` | `"pending" \| "current" \| "complete"` | `complete` means `next()` validated the step and moved on, and its data has not changed since. The step being shown is always `current`. See [Step state](https://stepperize.com/docs/v9/react/concepts/step-state). |
| `issues(id?)` | `Issue[] \| undefined` | Issues of the last failed validation of a step (a rejected `next()` or a `validate()`), the current one by default, until its data changes. |
| `canGoTo(id)` | `boolean` | Whether `goTo(id)` is allowed right now. Does not run the guard. |
| `match(handlers)` | The handler's result | Runs the handler of the current step with `(step, data)`. Exhaustive. |
| `snapshot()` | `Snapshot` | Everything needed to resume the flow. |

## Actions [#actions]

| Method | Description |
| --- | --- |
| `next(data?)` | Saves `data` for the current step, validates it and moves on. On a final step it finishes the flow. |
| `prev()` | Goes back to the step the person came from, or to the previous step in the list. Never validates. |
| `goTo(id)` | Jumps to a step. Does not validate; `linear` and the guard apply. |
| `validate(id?)` | Checks the data of a step, the current one by default, against its schema without moving. Resolves with the issues, or `undefined` when it is valid. |
| `setData(id, data)` | Replaces the data of a step, right away. A complete step whose data changes is no longer complete. |
| `reset()` | Back to the initial snapshot. Cancels a running move. |
| `restore(snapshot)` | Replaces the parts of the state you pass and keeps the rest, without validation or guards. Cancels a running move. |

The actions are the same functions on every stepper of a flow, and they always
act on the flow as it is now. `setData`, `reset` and `restore` return nothing.

### validate [#validate]

```tsx
const issues = await stepper.validate(); // the current step
if (issues) showErrors(issues);

await stepper.validate("shipping"); // any step, by id
```

`validate` runs the step's schema on its stored data and remembers the
result: `stepper.issues(id)` returns the same issues until the data changes. It
does not move, does not mark the step complete, does not run the guard and does
not call `onChange`. A step without a schema is always valid.

### setData and completion [#setdata-and-completion]

A step is complete while its data is the data `next()` validated. Writing a
different value with `setData` makes the step not complete and removes its
entry from `output`. In a [linear](https://stepperize.com/docs/v9/react/api/options#linear) flow the
steps completed after it stop being complete too, so they are reached through
`next()` again. Writing the same value (compared with `Object.is`) does
nothing: no change, no `onChange`.

## Results [#results]

`next`, `prev` and `goTo` resolve with a result and do not throw for expected
outcomes.

```ts
type Result =
  | { accepted: true; to: StepId | null; data: FlowData }
  | { accepted: false; reason: Reason; issues?: Issue[] };
```

`to` is `null` when the flow finished.

| Reason | Meaning |
| --- | --- |
| `invalid` | The step's schema rejected its data. `issues` says why. |
| `guard` | Your guard returned `false`. |
| `policy` | `linear` does not allow jumping to that step. |
| `pending` | Another move is still running. |
| `boundary` | `prev()` was called with nowhere to go back to. |
| `finished` | `next()` was called after the flow finished. Any move, a `setData` with a new value, `reset()` or `restore()` reopens it. |
| `cancelled` | `reset()`, `restore()` or unmounting interrupted the move. |

```tsx
const result = await stepper.next(values);
if (result.accepted) {
  if (result.to === null) toast("Done");
} else if (result.reason === "invalid") {
  showErrors(result.issues);
}
```

## What throws [#what-throws]

- An exception from your own schema, guard or `next` branch is not caught: the
  promise rejects with it, and the flow stays where it was.
- An exception or a rejected promise from `onFinish` rejects `next()` too. The
  final step is already complete, but the flow is not finished, so `next()` can
  be called again.
- `goTo` and `setData` with an id that is not in the definition throw
  [SZ102](https://stepperize.com/docs/v9/core/errors#sz102) immediately. TypeScript prevents it
  unless the id was cast.

## Timing [#timing]

A move with nothing asynchronous in it is finished when the call returns: the
flow has already changed, and the promise is already resolved. `"pending"`
only happens while an async schema, guard or `onFinish` is running.

```tsx
stepper.next(); // moves to the second step
stepper.next(); // moves to the third: the first call had finished
```

In an event handler this means two calls in a row make two moves. To make one
move depend on the other, await the result.
