Stepperize v9Explore the changes
Skip to Content
Stepperize

createStepper

Create a flow and drive it.

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

const flow = createStepper(steps, options);
ParameterDescription
stepsAt least one step with a unique id, an optional schema, and any other field.
optionsOptional. The same options every binding accepts.

The flow

A flow has every property and action of a stepper. Unlike the stepper a hook returns, which describes one moment, reads on a flow always return the latest state:

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.

MemberDescription
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

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

// 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

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.

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

TypeDescription
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>, ReasonWhat 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.
Edit on GitHub

Last updated on

On this page