# createStepper

> Create a flow and drive it.

Source: https://stepperize.com/docs/v9/core/create-stepper

```ts
import { createStepper } from "@stepperize/core";

const flow = createStepper(steps, options);
```

| Parameter | Description |
| --- | --- |
| `steps` | At least one step with a unique `id`, an optional `schema`, and any other field. |
| `options` | Optional. The same [options](https://stepperize.com/docs/v9/react/api/options) every binding accepts. |

## The flow [#the-flow]

A flow has every property and action of a [stepper](https://stepperize.com/docs/v9/react/api/stepper).
Unlike the stepper a hook returns, which describes one moment, reads on a flow
always return the latest state:

```ts
await flow.next(values);
flow.current.id;
flow.isLast;
flow.data; // every step as it was typed
flow.output; // what the schemas produced for the complete steps
flow.isFinished;

await flow.validate(); // check the current step without moving
```

It adds four members for whoever owns it.

| Member | Description |
| --- | --- |
| `get()` | The current stepper: an immutable picture of the flow. A new object after every change, the same object until then. |
| `subscribe(listener)` | Calls `listener` after every change. Returns a function that unsubscribes. |
| `setOptions(options)` | Replaces the options. Bindings call it on every render so callbacks stay current. |
| `destroy()` | Cancels a running move and drops every listener. |

## Subscribing [#subscribing]

`get` and `subscribe` are the contract external stores expect, so connecting a
framework takes a few lines.

```ts
// React
const stepper = useSyncExternalStore(flow.subscribe, flow.get);

// Svelte
const stepper = readable(flow.get(), (set) => flow.subscribe(() => set(flow.get())));

// Vue
const stepper = shallowRef(flow.get());
onScopeDispose(flow.subscribe(() => (stepper.value = flow.get())));
```

The object `get()` returns is what the React hooks call a stepper. It is
immutable: one you kept keeps describing the moment it was taken, and `get()`
returns the same object until something changes, which is what external-store
APIs require.

## Options that change [#options-that-change]

`setOptions` replaces every option except `snapshot`, which is only read when
the flow is created. A binding calls it whenever its owner re-renders, so
callbacks never go stale. When the `step` option changes, the flow follows it;
see [The step in the URL](https://stepperize.com/docs/v9/react/guides/url).

## Cleaning up [#cleaning-up]

Call `destroy()` when the owner goes away. It cancels a move that is still
running (its promise resolves with `reason: "cancelled"`) and removes every
listener.

## Types [#types]

| Type | Description |
| --- | --- |
| `Step` | `{ id: string; schema?: StandardSchemaV1 }` plus your own fields. |
| `Id<S>` | Union of the step ids. |
| `Input<S, I>`, `Output<S, I>` | What a step stores, and what its schema produces. |
| `FlowData<S>` | The data of every step, by id: schema inputs. |
| `FlowOutput<S>` | What the schema of every complete step produced, by id: schema outputs. |
| `Options<S>` | The options. |
| `Stepper<S>`, `Flow<S>` | What `get()` returns, and a live flow. |
| `Snapshot<S>` | `{ step, history, data, complete }`. |
| `Result<S>`, `Reason` | What a move resolves with. `Reason` is `"invalid" \| "guard" \| "policy" \| "pending" \| "boundary" \| "finished" \| "cancelled"`. |
| `GuardContext<S>` | The argument of `guard`. |
| `Issue` | `{ message, path? }`, as Standard Schema defines it. |
