# Stepperize v8

Type-safe step-by-step flows for React 18 and 19. Web primitives are unstyled; the logic hook can be used with custom React Native UI. The v8 branch prepares the next major release.

## Ownership

Define the immutable step array once at module scope:

```tsx
import { defineStepper } from "@stepperize/react";
const checkout = defineStepper([
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "review", title: "Review" },
], { linear: true });
```

- checkout.useStepper(options?) ALWAYS creates local independent state, even inside a Provider.
- checkout.Provider owns and shares state without markup.
- checkout.Stepper.Root owns and shares state with a container and orientation.
- checkout.useStepperContext() consumes the nearest matching owner; throws when missing.
- checkout.useStepperContext(selector, isEqual?) subscribes to a selected value. Default comparison is Object.is. Pure object selectors are safe; supply equality to skip equivalent object selections.
- A Root always creates its own scope, including under a Provider. Different definitions never share contexts.

## Instance

State: steps, current, id, index, count, progress (index / (count - 1), or 1 for a single step), isFirst, isLast, canPrev, canNext, isPending, completed.
Queries: is(id), status(id), isComplete(id?), canGoTo(id).
Render: match({ shipping: (step, data) => ..., payment: ..., review: ... }), exhaustive and data typed per step schema input.
Static helpers live on definition: steps, get(id), at(index), parseStep(unknown), validate(id, value).

## Navigation

next({data?, complete?}?), prev({data?, complete?}?), goTo(id, {data?, complete?, bypassPolicy?}?), reset({keepData?, keepCompleted?}?).
All return Promise<NavigationResult>: {accepted:true,from,to} or {accepted:false,reason}.
Reasons: guard, policy, pending, boundary, same-step, invalid-step, cancelled.
Await the result and test result.accepted, NEVER its truthiness. Exceptions from callbacks reject the promise.

Data payloads belong to the SOURCE step, and complete:true marks the SOURCE complete. Both commit atomically after guard acceptance. At the final step next() returns boundary; use an application submit action.
Linear policy applies to goTo, canGoTo, triggers and list keyboard navigation. It allows current, previous and immediate next steps. Intentional branches opt out with bypassPolicy:true; the guard always still runs.
Reset restores mount-time defaultStep/defaultData/defaultCompleted through the guard. Preserve selected state with keepData/keepCompleted. Controlled owners must apply the requested defaults.

## Data and completion

Data API: get(id?), set(value), set(id,value), update(id,previous=>next), all(), clear(id?), reset().
update composes against preceding writes in the same event. Treat snapshots/previous data as immutable.
clear empties data; data.reset restores mount defaults only. Navigation reset restores all state by default.
Schemas follow Standard Schema v1 (Zod, Valibot, ArkType). get(id), set(id,value), update and match handlers use schema INPUT types. validate returns schema OUTPUT without replacing stored drafts automatically.
setComplete(id?,value=true) and isComplete(id?) are explicit business completion. status is positional: active, previous, upcoming. Previous does not mean complete.

## Owner options

Definition defaults: defaultStep, defaultData, defaultCompleted, linear.
useStepper/Provider/Root: those defaults plus step/onStepChange, data/onDataChange, completed/onCompletedChange, onInvalidStep, beforeStepChange.
Defaults are captured at mount. Each controlled piece remains authoritative until props update; external prop changes do not run guards.

beforeStepChange(ctx) returns false to reject, true/undefined to allow, optionally asynchronously. Context includes from,to,fromIndex,toIndex,direction,data,statuses,signal,validate(idOrStep?). direction is next/prev/goto/reset. validate() uses source data including staged payload.
Async guards set isPending and reject overlapping moves. Owner unmount, authoritative state changes or data/completion writes cancel obsolete guards. Pass signal to cancellable work. onStepChange is a synchronous accepted-transition notification; awaitable blocking work belongs in the guard.

## Primitives

Generated Stepper: Root, List, Items, Item, Trigger, Content, Indicator, Title, Description, Separator, Actions, Next, Prev.
Items iterates steps; Item gets an explicit step id or derives it under Items. List and Separator inherit Root orientation unless overridden. Trigger has type=button, instance-unique ARIA ids and keyboard navigation. Content forceMount retains hidden inactive panels. data-status is positional; data-complete is explicit completion. Root may render children or ({stepper}) => children. createStepperPrimitives is INTERNAL and not exported.

## Forms

Keep editable field state and errors in the form library. Validate on form submit, then await stepper.next({data:values,complete:true}). Seed a remounted form from stepper.data.get(id). Shared form children use useStepperContext. A guard can protect non-form navigation too. Final submission belongs to the application.

## Documentation

- /docs/v8/guides/local-and-shared-state — complete examples and interactive ownership demo
- /docs/v8/api/react/use-stepper-context — selectors and scopes
- /docs/v8/guides/navigation — outcomes, guards, policy and reset
- /docs/v8/forms — form integration patterns
- /docs/v8/migration/v8 — upgrade from v7
- /docs/v8/migration/v7 — historical v6-to-v7 guide; apply v8 migration afterwards
- /docs/v8/changelog

Old v7 auto-sharing useStepper calls, boolean navigation results, implicit goTo bypass and step-only reset are obsolete in v8. Older nested APIs (navigation.next, metadata, Scoped) are also obsolete.

For custom markup or React Native, @stepperize/react/headless exports defineStepper with the same state API but no Stepper UI primitives. Import from @stepperize/react for the generated accessible components. Bundle measurements: https://stepperize.com/docs/v8/guides/performance

# Index

Every v8 docs page as markdown, in sidebar order, then Stepper Studio and the Blocks.

## Docs: Start

- [Introduction](https://stepperize.com/llms.mdx/docs/v8): Learn how Stepperize helps you build typed multi-step flows.
- [Installation](https://stepperize.com/llms.mdx/docs/v8/getting-started/installation): Install Stepperize in your React project.
- [First stepper](https://stepperize.com/llms.mdx/docs/v8/getting-started/first-stepper): Build your first typed multi-step flow.
- [Migrating to v8](https://stepperize.com/llms.mdx/docs/v8/migration/v8): Upgrade from v7 to explicit state ownership and consistent navigation.
- [Changelog](https://stepperize.com/llms.mdx/docs/v8/changelog): Review recent documentation and package changes.

## Docs: Core concepts

- [Steps & ids](https://stepperize.com/llms.mdx/docs/v8/getting-started/concepts): Model each step with a stable typed id.
- [The stepper instance](https://stepperize.com/llms.mdx/docs/v8/core-concepts/stepper-instance): Understand the object that drives state, navigation, and rendering.
- [The navigation lifecycle](https://stepperize.com/llms.mdx/docs/v8/core-concepts/navigation-lifecycle): Understand staged data, guards, atomic commits and results.
- [Status vs completion](https://stepperize.com/llms.mdx/docs/v8/core-concepts/status-vs-completion): Understand how step status and completion differ.
- [Controlled vs uncontrolled](https://stepperize.com/llms.mdx/docs/v8/core-concepts/controlled-vs-uncontrolled): Choose where stepper state should live.

## Docs: Build

- [Navigation](https://stepperize.com/llms.mdx/docs/v8/guides/navigation): Save, complete, guard, branch and reset with consistent outcomes.
- [Shared state](https://stepperize.com/llms.mdx/docs/v8/guides/shared-state): Configure shared and controlled flows with explicit instance ownership.
- [Local and shared state](https://stepperize.com/llms.mdx/docs/v8/guides/local-and-shared-state): Choose who owns a flow, with complete examples and an interactive comparison.
- [Primitives](https://stepperize.com/llms.mdx/docs/v8/guides/primitives): Build accessible custom UI with unstyled primitives.
- [Styling](https://stepperize.com/llms.mdx/docs/v8/guides/styling): Style the headless primitives with the data attributes the API exposes.

## Docs: Forms

- [Building multi-step forms](https://stepperize.com/llms.mdx/docs/v8/forms): Build multi-step forms using your preferred form library.
- [Core patterns](https://stepperize.com/llms.mdx/docs/v8/forms/patterns): Learn the core patterns behind reliable multi-step forms.
- [Schema & validate()](https://stepperize.com/llms.mdx/docs/v8/forms/schema-validation): Validate step data with Standard Schema.
- [Common problems](https://stepperize.com/llms.mdx/docs/v8/forms/common-problems): Solve common issues in multi-step forms.
- [React Hook Form](https://stepperize.com/llms.mdx/docs/v8/forms/react-hook-form): A complete shared form flow with validation, review and final submission.
- [TanStack Form](https://stepperize.com/llms.mdx/docs/v8/forms/tanstack-form): A complete shared form flow with validation, review and final submission.
- [Conform](https://stepperize.com/llms.mdx/docs/v8/forms/conform): A complete shared form flow with validation, review and final submission.

## Docs: Reference

- [defineStepper](https://stepperize.com/llms.mdx/docs/v8/api/react/define-stepper): Reference the API for defining typed flows.
- [useStepper](https://stepperize.com/llms.mdx/docs/v8/api/react/use-stepper): Create an independent local stepper instance.
- [useStepperContext](https://stepperize.com/llms.mdx/docs/v8/api/react/use-stepper-context): Read a shared instance or subscribe to a selected value.
- [Stepper instance](https://stepperize.com/llms.mdx/docs/v8/api/react/stepper-instance): Reference the runtime API returned by the hook.
- [Provider](https://stepperize.com/llms.mdx/docs/v8/api/react/provider): Own and share one stepper instance without adding markup.
- [Primitives](https://stepperize.com/llms.mdx/docs/v8/api/react/primitives): Reference the unstyled components for custom stepper UI.
- [Types](https://stepperize.com/llms.mdx/docs/v8/api/react/types): Reference the public React package types.

## Docs: Help

- [FAQ](https://stepperize.com/llms.mdx/docs/v8/getting-started/faq): Find quick answers to common Stepperize questions.
- [Troubleshooting](https://stepperize.com/llms.mdx/docs/v8/getting-started/troubleshooting): Fix common setup and runtime issues.

## Docs: Resources

- [React Activity](https://stepperize.com/llms.mdx/docs/v8/guides/react-activity): Preserve step state, forms, and expensive UI trees while navigating.
- [Performance](https://stepperize.com/llms.mdx/docs/v8/guides/performance): Compare v7 and v8 across local state, shared subscriptions, navigation, guards, resets, validation and bundle size, with reproducible measurements.
- [Production checklist](https://stepperize.com/llms.mdx/docs/v8/production/checklist): Prepare your stepper for production.
- [Core utilities](https://stepperize.com/llms.mdx/docs/v8/api/core/overview): Reference the framework-agnostic utilities.

## Stepper Studio

- [Stepper Studio guide for agents](https://stepperize.com/studio.md): build a flow config, encode it, and install the generated code (on shadcn/ui, with your choice of form and validation library, framework and routing) with the shadcn CLI.
- [Studio config JSON Schema](https://stepperize.com/r/studio/schema.json): the exact shape the Studio registry endpoint accepts.
- [Stepper Studio](https://stepperize.com/studio): the visual editor, for humans.

## Blocks

Copy-paste stepper UIs built on the primitives. Install one with `npx shadcn@latest add https://stepperize.com/r/<id>.json`; the full index is at https://stepperize.com/r/registry.json.

- [Progress Bar Stepper](https://stepperize.com/r/progress-bar.json) (Layouts & Navigation): A single progress bar that fills as the user advances.
- [Segmented Tabs Stepper](https://stepperize.com/r/segmented.json) (Layouts & Navigation): Segmented control where each step is a selectable tab.
- [Circular Stepper](https://stepperize.com/r/circular.json) (Layouts & Navigation): An SVG progress ring around the current step number.
- [Breadcrumb Stepper](https://stepperize.com/r/breadcrumb.json) (Layouts & Navigation): A breadcrumb-style trail of steps with chevrons.
- [Vertical Stepper](https://stepperize.com/r/vertical-stepper.json) (Layouts & Navigation): A sidebar-style vertical layout: step rail on the left, long-form content on the right, collapsing to a compact nav on mobile.
- [User Onboarding](https://stepperize.com/r/user-onboarding.json) (Onboarding): A three-step account onboarding flow with per-step validation.
- [Organization Setup](https://stepperize.com/r/org-setup.json) (Onboarding): Workspace, branding, and members setup for a new SaaS tenant.
- [Team Invitations](https://stepperize.com/r/team-invites.json) (Onboarding): Collect invites into draft flow data, then review and send them.
- [Conditional Onboarding](https://stepperize.com/r/conditional-onboarding.json) (Onboarding): Onboarding whose path is computed from an earlier answer: team accounts visit the invite step, personal accounts skip it.
- [Product Tour](https://stepperize.com/r/product-tour.json) (Onboarding): A card-style onboarding walkthrough with dot indicators and free navigation.
- [Course Player](https://stepperize.com/r/course-player.json) (Onboarding): A lesson playlist with typed per-lesson metadata and a final quiz.
- [Validated Checkout](https://stepperize.com/r/validated-checkout.json) (Commerce): A checkout where each step has a Zod schema; validate() inside a beforeStepChange guard blocks invalid input before the review step.
- [Plan Picker](https://stepperize.com/r/plan-picker.json) (Commerce): Choose a plan, set billing, then pay — billing path branches on the plan.
- [Appointment Booking](https://stepperize.com/r/appointment.json) (Commerce): Service, professional, time slot, and confirmation.
- [Two-Factor Setup](https://stepperize.com/r/two-factor.json) (Auth & Verification): Pick a method, verify a code, save backup codes.
- [KYC Verification](https://stepperize.com/r/kyc-verification.json) (Auth & Verification): Identity, document, and selfie verification steps.
- [Device Pairing](https://stepperize.com/r/device-pairing.json) (Auth & Verification): Discover, pair, configure, and ready a device over an async transition.
- [Async Provisioning](https://stepperize.com/r/async-provisioning.json) (Async & Status): A deploy flow with an async guarded transition, pending UI, a failed first attempt, and a retry path.
- [Order Tracking](https://stepperize.com/r/order-tracking.json) (Async & Status): A shipment tracker driven by typed per-step metadata (carrier, location, ETA).
- [CI/CD Pipeline](https://stepperize.com/r/cicd-pipeline.json) (Async & Status): Build, test, deploy, verify pipeline status with typed stage metadata.
- [Approval Flow](https://stepperize.com/r/approval-flow.json) (Async & Status): A multi-stage submission and approval chain.
- [Approval Timeline](https://stepperize.com/r/approval-timeline.json) (Async & Status): A vertical audit timeline where each step carries typed metadata (actor, role, SLA hours) read straight off `step` and `stepper.current` with full inference.
- [Decision Tree](https://stepperize.com/r/decision-tree.json) (Flow Logic): A plan finder that branches to different follow-up questions and converges on a result computed from the answers.
- [Save & Resume](https://stepperize.com/r/save-resume.json) (Flow Logic): A controlled wizard whose active step is synced to localStorage and the URL hash.
- [AI Workflow](https://stepperize.com/r/ai-workflow.json) (Flow Logic): An iterative generation flow where each run is appended to flow data and Refine loops back to the prompt.
- [Typed Wizard](https://stepperize.com/r/typed-wizard.json) (Flow Logic): An exhaustive stepper.match() over every step id — add or remove a step and the match becomes a compile error until you handle it.
- [Dashboard Wizard](https://stepperize.com/r/dashboard-wizard.json) (Flow Logic): A SaaS settings wizard with sticky step nav, per-step validation, and an unsaved-changes guard wired through beforeStepChange and beforeunload.
- [Progress Overview](https://stepperize.com/r/progress-overview.json) (Flow Logic): A progress panel that computes percent complete and an ETA from typed per-step metadata (estimated minutes).

## Optional

- [Full v8 documentation](https://stepperize.com/llms-full.txt): every page above in one markdown file.
- [Changelog](https://stepperize.com/changelog)
- [v7 documentation](https://stepperize.com/docs/v7): legacy API, only for projects still on v7.
- [v6 documentation](https://stepperize.com/docs/v6): legacy API, only for projects still on v6.
- [v5 documentation](https://stepperize.com/docs/v5): legacy API, only for projects still on v5.
- [v4 documentation](https://stepperize.com/docs/v4): legacy API, only for projects still on v4.
- [v3 documentation](https://stepperize.com/docs/v3): legacy API, only for projects still on v3.
- [v2 documentation](https://stepperize.com/docs/v2): legacy API, only for projects still on v2.