# Options

> Everything a flow can be configured with.

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

The same options are accepted by `defineStepper` (as defaults), `useStepper`,
`Provider`, `Stepper.Root` and `create`. Callbacks always see your latest
props: there is nothing to memoize.

| Option | Type | Description |
| --- | --- | --- |
| [`linear`](#linear) | `boolean` | Only move forward through `next()`. Default `false`. |
| [`next`](#next) | `object` | Where each step leads. |
| [`guard`](#guard) | `function` | Runs before every move and can cancel it. |
| [`snapshot`](#snapshot) | `Partial<Snapshot>` | Where the flow starts. Read once. |
| [`step`](#step) | `string \| null` | An outside value the flow follows, such as the URL. |
| [`onChange`](#onchange) | `(snapshot) => void` | Called after the step, the data or the completion changes. |
| [`onFinish`](#onfinish) | `(output, data) => void \| Promise` | Called once when the flow ends. |
| [`onInvalidStep`](#oninvalidstep) | `(current) => void` | Called when the flow cannot follow `step`. |

Options passed to a flow are merged over the definition's defaults, one
option at a time.

```tsx
const checkout = defineStepper(steps, { linear: true });

checkout.useStepper(); // linear
checkout.useStepper({ linear: false }); // not linear
```

## linear [#linear]

In a linear flow, `goTo` and the triggers only reach the current step and the
steps already [complete](https://stepperize.com/docs/v9/react/concepts/step-state). Everything else
is reached through `next()`, which validates. `prev()` is always allowed.

Editing a complete step with `setData` makes it, and the steps completed after
it, not complete: nothing past an edited step can be reached without
validating it again.

Without `linear`, any step can be opened at any time.

See [Linear flows](https://stepperize.com/docs/v9/react/guides/navigation#linear-flows).

## next [#next]

A map from step id to where it leads. See
[Branching](https://stepperize.com/docs/v9/react/guides/branching).

```tsx
next: {
  account: (data) => (data.type === "team" ? "team" : "payment"),
  profile: (_data, flow) => (flow.account?.type === "team" ? "invite" : "done"),
  rejected: null,
}
```

- A function receives the step's validated data, then the data of every
  step, and returns a step id, or `null` to end the flow.
- `null` ends the flow at that step.
- No entry: the following step in the list, or the end after the last one.

A branch that returns an id that is not in the definition makes `next()`
reject with [SZ102](https://stepperize.com/docs/v9/core/errors#sz102).

## guard [#guard]

```tsx
guard: async ({ from, to, direction, data, signal }) => {
  if (direction !== "next") return;
  const response = await fetch("/api/check", {
    method: "POST",
    body: JSON.stringify(data),
    signal,
  });
  return response.ok;
}
```

Runs after validation and before every `next`, `prev` and `goTo`. Return
`false` to cancel the move; anything else, including nothing, allows it. It
may be async.

| Field | Description |
| --- | --- |
| `from` | The step being left. |
| `to` | The step being entered, or `null` when the flow is finishing. |
| `direction` | `"next"`, `"prev"` or `"goTo"`. |
| `data` | The data of every step as it will be if the move is accepted. |
| `signal` | Aborted if the move is cancelled by `reset`, `restore` or unmounting. |

It is not called by `setData`, `reset` or `restore`. See
[Guard a move](https://stepperize.com/docs/v9/react/guides/navigation#guard-a-move).

## snapshot [#snapshot]

```ts
type Snapshot = {
  step: string; // the current step
  history: string[]; // the path taken, which prev() walks back
  data: object; // the data of every step, by id
  complete: string[]; // the steps next() has validated, in that order
};
```

Pass any part of it. It is read when the flow is created; to apply one later,
call `stepper.restore(snapshot)`. Ids that are not in the definition are
dropped from `step`, `history` and `complete`.

A snapshot does not carry `output`. Steps restored as complete get theirs when
the flow finishes: see [onFinish](#onfinish).

`reset()` returns to this snapshot. See
[Saving and resuming](https://stepperize.com/docs/v9/react/guides/persistence).

## step [#step]

A step id that lives somewhere else, typically the URL. The flow starts on it
and goes to it whenever the value changes, the way `goTo` would: `linear` and
the guard apply. Any string is accepted; `null` and `undefined` mean "nothing
to follow".

When both `step` and `snapshot.step` are given, `step` wins if the flow is
allowed to be there.

See [The step in the URL](https://stepperize.com/docs/v9/react/guides/url).

## onChange [#onchange]

Called with the new snapshot after anything a saved copy should know about:

- an accepted `next`, `prev` or `goTo`,
- a `next()` rejected by the schema, because the data that was passed is kept,
- `setData` with a new value, `reset` and `restore`.

It is not called when only `isPending`, `isFinished` or the issues change (so
not by `validate()`), when a guard refuses a move, or when the flow cannot
follow `step`.

Because `setData` calls it, debounce slow writes if you save drafts while
typing.

## onFinish [#onfinish]

Called once when `next()` completes a final step: the last step of the list, a
step whose `next` entry is `null`, or a branch that returned `null`.

```tsx
onFinish: async (output, data) => {
  await api.createOrder(output);
},
```

| Argument | What it holds |
| --- | --- |
| `output` | What the schema of every complete step produced: transforms, coercions and defaults applied. Typed by each schema's output. |
| `data` | Every step as it was typed, drafts of steps that were never completed included. Typed by each schema's input. |

Return a promise and the flow stays pending (`isPending`) until it settles.
When it resolves, `isFinished` becomes `true`. When it rejects, `next()` rejects
with the same error and the flow is not finished, so the person can try again.

The flow stays on that step. Once finished, `next()` is refused with the reason
`finished`, so a second press does not submit twice. Any move, a `setData` with
a new value, `reset()` or `restore()` reopens the flow. See
[Finishing the flow](https://stepperize.com/docs/v9/react/guides/navigation#finish-the-flow).

Steps that were restored as complete from a snapshot have no output yet, so
they are validated once more right before `onFinish`. If one fails, the flow
does not finish: `next()` resolves with `invalid`, the issues are stored under
that step (`stepper.issues(id)`) and the step is no longer complete.

## onInvalidStep [#oninvalidstep]

Called with the id of the step the flow is on when it cannot follow `step`:

- the value is not a step of the definition,
- a linear flow does not allow that step yet,
- the guard refused the move,
- or another move was still running.

Use it to correct the source without adding a history entry:

```tsx
onInvalidStep: (current) => router.replace(`/checkout/${current}`),
```
