Stepperize

https://stepperize.vercel.app/docs/react
Admin
Stepperize is a versatile React library for creating flexible, type-safe Stepper components that...
Tokens:47,941
Snippets:338
Trust Score:7.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Conform with Zod

Source: https://stepperize.vercel.app/docs/react/examples/forms

Install the Conform form library along with Zod for validation.

```bash
pnpm add @conform-to/react @conform-to/zod zod
```

--------------------------------

### Full Example: Minimal Stepper Component

Source: https://stepperize.vercel.app/docs/react/my-first-stepper

A complete React component demonstrating the minimal stepper setup using defineStepper and useStepper, including navigation buttons and conditional rendering for step content.

```typescript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { useStepper } = defineStepper(
  { id: "name", title: "Name" },
  { id: "email", title: "Email" },
  { id: "confirm", title: "Confirm" },
  { id: "done", title: "Done" },
);

export function MyFirstStepper() {
  const stepper = useStepper();
  return (
    <>
      <p>Step: <strong>{stepper.state.current.data.title}</strong></p>
      <div>
        {stepper.flow.switch({
          name: () => <p>What is your name?</p>,
          email: () => <p>What is your email?</p>,
          confirm: () => <p>Please confirm your details.</p>,
          done: () => <p>All done!</p>,
        })}
      </div>
      <div>
        {stepper.state.isLast ? (
          <button onClick={() => stepper.navigation.reset()}>Reset</button>
        ) : (
          <>
            <button onClick={() => stepper.navigation.prev()} disabled={stepper.state.isFirst}>Back</button>
            <button onClick={() => stepper.navigation.next()}>Next</button>
          </>
        )}
      </div>
    </>
  );
}
```

--------------------------------

### Full Example with Custom Styling and Content

Source: https://stepperize.vercel.app/docs/react/examples/basic

A comprehensive example integrating custom step indicators, styled triggers, and content for each step. It also includes navigation buttons and conditional rendering for the reset option.

```jsx
import React from "react";
import { defineStepper } from "@stepperize/react";
import { useStepItemContext } from "@stepperize/react/primitives";

const { Stepper } = defineStepper(
  { id: "a", title: "First" },
  { id: "b", title: "Second" },
  { id: "c", title: "Third" }
);

function StepNumber() {
  const item = useStepItemContext();
  return <span>{item.index + 1}</span>;
}

function Trigger({ children }: { children: React.ReactNode }) {
  return (
    <Stepper.Trigger className="rounded-full border border-gray-300 bg-white px-2 py-1 text-sm data-[status=active]:bg-blue-100 dark:data-[status=active]:bg-blue-900/40">
      {children}
    </Stepper.Trigger>
  );
}

export function StepperWithNumberedIndicator() {
  return (
    <Stepper.Root>
      {({ stepper }) => (
        <>
          <Stepper.List className="m-0 flex list-none flex-wrap gap-2 p-0">
            {stepper.state.all.map((step) => (
              <React.Fragment key={step.id}>
                <Stepper.Item step={step.id}>
                  <Trigger>
                    <Stepper.Indicator className="inline-flex size-4 items-center justify-center rounded-full bg-inherit text-xs font-semibold">
                      <StepNumber />
                    </Stepper.Indicator>
                    <Stepper.Title render={(props) => <span {...props}>{step.title}</span>} />
                  </Trigger>
                </Stepper.Item>
                {step.id !== "c" && <span className="self-center text-gray-400">→</span>}
              </React.Fragment>
            ))}
          </Stepper.List>
          <div className="mt-4 min-h-10">
            <Stepper.Content step="a"><p>First step content</p></Stepper.Content>
            <Stepper.Content step="b"><p>Second step content</p></Stepper.Content>
            <Stepper.Content step="c"><p>Third step content</p></Stepper.Content>
          </div>
          <div className="mt-4 flex flex-wrap gap-2">
            {stepper.state.isLast ? (
              <button type="button" onClick={() => stepper.navigation.reset()}>
                Reset
              </button>
            ) : (
              <>
                <Stepper.Prev>Previous</Stepper.Prev>
                <Stepper.Next>Next</Stepper.Next>
              </>
            )}
          </div>
        </>
      )}
    </Stepper.Root>
  );
}
```

--------------------------------

### Full Example: Custom Step Indicator

Source: https://stepperize.vercel.app/docs/react/examples/basic

A comprehensive example demonstrating how to implement custom step indicators using render props within `Stepper.Indicator` for enhanced visual feedback.

```javascript
import { Stepper } from "stepperize";

const steps = [
  { id: "details", label: "Details" },
  { id: "plan", label: "Plan" },
  { id: "payment", label: "Payment" },
];

function CustomIndicatorStepper() {
  return (
    <Stepper.Root steps={steps}>
      <Stepper.List>
        { (step) => (
          <Stepper.Item key={step.id} step={step.id}>
            <Stepper.Indicator>
              { (state) => (
                <span
                  style={{
                    display: "flex",
                    alignItems: "center",
                    justifyContent: "center",
                    width: 24,
                    height: 24,
                    borderRadius: "50%",
                    backgroundColor: state.isActive ? "blue" : "gray",
                    color: "white",
                  }}
                >
                  {state.index + 1}
                </span>
              ) }
            </Stepper.Indicator>
            <Stepper.Label>{step.label}</Stepper.Label>
          </Stepper.Item>
        ) }
      </Stepper.List>

      <Stepper.Content step="details">
        <p>Enter your details here.</p>
      </Stepper.Content>
      <Stepper.Content step="plan">
        <p>Choose your plan.</p>
      </Stepper.Content>
      <Stepper.Content step="payment">
        <p>Enter your payment information.</p>
      </Stepper.Content>

      <Stepper.Actions>
        <Stepper.Prev />
        <Stepper.Next />
      </Stepper.Actions>
    </Stepper.Root>
  );
}
```

--------------------------------

### Complete Stepper Example

Source: https://stepperize.vercel.app/docs/react/api-references/primitives

This example demonstrates how to use the Stepper primitives to build a complete checkout stepper UI. It includes the list of steps, content for each step, and navigation actions. Ensure Stepper.Root is used to provide the stepper state.

```jsx
import React from "react"
import { defineStepper } from "@stepperize/react"

const { Stepper } = defineStepper(
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" },
  { id: "confirmation", title: "Confirmation" }
);

function CheckoutStepper() {
  return (
    <Stepper.Root>
      {({ stepper }) => (
        <>
          <Stepper.List>
            {stepper.state.all.map((step) => (
              <Stepper.Item key={step.id} step={step.id}>
                <Stepper.Trigger>
                  <Stepper.Indicator />
                  <Stepper.Title>{step.title}</Stepper.Title>
                </Stepper.Trigger>
                <Stepper.Separator />
              </Stepper.Item>
            ))}
          </Stepper.List>

          <Stepper.Content step="shipping">
            Shipping form here
          </Stepper.Content>
          <Stepper.Content step="payment">
            Payment form here
          </Stepper.Content>
          <Stepper.Content step="confirmation">
            Confirmation here
          </Stepper.Content>

          <Stepper.Actions>
            <Stepper.Prev>Previous</Stepper.Prev>
            <Stepper.Next>Next</Stepper.Next>
          </Stepper.Actions>
        </>
      )}
    </Stepper.Root>
  );
}
```

--------------------------------

### Install TanStack Form with Zod

Source: https://stepperize.vercel.app/docs/react/examples/forms

Install TanStack Form and Zod for form handling and validation.

```bash
pnpm add @tanstack/react-form zod
```

--------------------------------

### Install @stepperize/react with Bun

Source: https://stepperize.vercel.app/docs/react/installation

Use this command to add @stepperize/react to your project if you are using Bun as your package manager.

```bash
bun add @stepperize/react 
```

--------------------------------

### Scoped Component - Props

Source: https://stepperize.vercel.app/docs/react/api-references/scoped

Details the available props for the Scoped component, including `initialStep` for setting the starting step and `initialMetadata` for pre-populating step-specific data. It also shows how to use these props in a practical example.

```APIDOC
## Scoped Component - Props

### Description
The `Scoped` component accepts several props to configure the initial state of the stepper.

### Props
Name| Type| Description  
---|---|---
`initialStep`| `Get.Id<Steps>`| Initial active step ID  
`initialMetadata`| `Partial<Record<Get.Id<Steps>, Metadata>>`| Initial metadata per step  
`children`| `React.ReactNode`| Content to render  

### Usage with Props
```jsx
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Scoped, useStepper } = defineStepper(
  { id: "first", title: "First" },
  { id: "second", title: "Second" },
  { id: "last", title: "Last" }
);

export const MyScopedStepper = () => (
  <Scoped
    initialStep="second"
    initialMetadata={{ first: { completed: true }, second: null, last: null }}
  >
    <StepContent />
  </Scoped>
);

const StepContent = () => {
  const stepper = useStepper();
  return <div>Current: {stepper.state.current.data.title}</div>;
};
```
```

--------------------------------

### Full Example: Horizontal Stepper

Source: https://stepperize.vercel.app/docs/react/examples/basic

A complete example of a horizontal stepper, integrating all the necessary components for step definition, navigation, and content display.

```javascript
import { Stepper } from "stepperize";

const steps = [
  { id: "details", label: "Details" },
  { id: "plan", label: "Plan" },
  { id: "payment", label: "Payment" },
];

function HorizontalStepper() {
  return (
    <Stepper.Root steps={steps}>
      <Stepper.List>
        { (step) => (
          <Stepper.Item key={step.id} step={step.id}>
            <Stepper.Label>{step.label}</Stepper.Label>
          </Stepper.Item>
        ) }
      </Stepper.List>

      <Stepper.Content step="details">
        <p>Enter your details here.</p>
      </Stepper.Content>
      <Stepper.Content step="plan">
        <p>Choose your plan.</p>
      </Stepper.Content>
      <Stepper.Content step="payment">
        <p>Enter your payment information.</p>
      </Stepper.Content>

      <Stepper.Actions>
        <Stepper.Prev />
        <Stepper.Next />
      </Stepper.Actions>
    </Stepper.Root>
  );
}
```

--------------------------------

### Full Example: Vertical Stepper

Source: https://stepperize.vercel.app/docs/react/examples/basic

A complete example of a vertical stepper, demonstrating the use of the `orientation='vertical'` prop for a different layout.

```javascript
import { Stepper } from "stepperize";

const steps = [
  { id: "details", label: "Details" },
  { id: "plan", label: "Plan" },
  { id: "payment", label: "Payment" },
];

function VerticalStepper() {
  return (
    <Stepper.Root steps={steps} orientation="vertical">
      <Stepper.List>
        { (step) => (
          <Stepper.Item key={step.id} step={step.id}>
            <Stepper.Label>{step.label}</Stepper.Label>
          </Stepper.Item>
        ) }
      </Stepper.List>

      <Stepper.Content step="details">
        <p>Enter your details here.</p>
      </Stepper.Content>
      <Stepper.Content step="plan">
        <p>Choose your plan.</p>
      </Stepper.Content>
      <Stepper.Content step="payment">
        <p>Enter your payment information.</p>
      </Stepper.Content>

      <Stepper.Actions>
        <Stepper.Prev />
        <Stepper.Next />
      </Stepper.Actions>
    </Stepper.Root>
  );
}
```

--------------------------------

### Install @stepperize/react with PNPM

Source: https://stepperize.vercel.app/docs/react/installation

Use this command to add @stepperize/react to your project if you are using PNPM as your package manager.

```bash
pnpm install @stepperize/react 
```

--------------------------------

### Install @stepperize/react with NPM

Source: https://stepperize.vercel.app/docs/react/installation

Use this command to add @stepperize/react to your project if you are using NPM as your package manager.

```bash
npm install @stepperize/react 
```

--------------------------------

### Install React Hook Form with Zod

Source: https://stepperize.vercel.app/docs/react/examples/forms

Install React Hook Form and the Zod resolver for validation.

```bash
pnpm add react-hook-form @hookform/resolvers zod
```

--------------------------------

### Install @stepperize/react with Yarn

Source: https://stepperize.vercel.app/docs/react/installation

Use this command to add @stepperize/react to your project if you are using Yarn as your package manager.

```bash
yarn add @stepperize/react 
```

--------------------------------

### Stepper State and Navigation Example

Source: https://stepperize.vercel.app/docs/react/api-references/hook

Demonstrates accessing stepper state properties like `current`, `isFirst`, and `isLast`, and utilizing navigation methods such as `next()`, `prev()`, `goTo(id)`, and `reset()`.

```javascript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { useStepper } = defineStepper(
  { id: "info", title: "Info" },
  { id: "review", title: "Review" },
  { id: "done", title: "Done" }
);

function NavExample() {
  const stepper = useStepper();
  return (
    <div>
      <p>Step {stepper.state.current.index + 1}: {stepper.state.current.data.title}</p>
      <button type="button" onClick={() => stepper.navigation.prev()} disabled={stepper.state.isFirst}>Back</button>
      <button type="button" onClick={() => stepper.navigation.next()} disabled={stepper.state.isLast}>Next</button>
      <button type="button" onClick={() => stepper.navigation.goTo("review")}>Jump to Review</button>
      <button type="button" onClick={() => stepper.navigation.reset()}>Reset</button>
    </div>
  );
}

```

--------------------------------

### Horizontal Stepper Example

Source: https://stepperize.vercel.app/docs/react/examples/basic

Implement a horizontal stepper with navigation controls. Use this for sequential processes where a clear left-to-right flow is desired.

```jsx
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Stepper } = defineStepper(
  { id: "account", title: "Account" },
  { id: "profile", title: "Profile" },
  { id: "done", title: "Done" }
);

function Trigger({ children }: { children: React.ReactNode }) {
  return (
    <Stepper.Trigger className="border border-gray-300 bg-white px-2 py-1 text-sm data-[status=active]:bg-blue-100 dark:data-[status=active]:bg-blue-900/40">
      {children}
    </Stepper.Trigger>
  );
}

export function HorizontalStepper() {
  return (
    <Stepper.Root>
      {({ stepper }) => (
        <>
          <Stepper.List className="m-0 flex list-none flex-wrap gap-2 p-0">
            {stepper.state.all.map((step) => (
              <React.Fragment key={step.id}>
                <Stepper.Item step={step.id}>
                  <Trigger>
                    <Stepper.Title render={(props) => <span {...props}>{step.title}</span>} />
                  </Trigger>
                </Stepper.Item>
                {step.id !== "done" && <span className="self-center text-gray-400">→</span>}
              </React.Fragment>
            ))}
          </Stepper.List>
          <div className="mt-4 min-h-12">
            <Stepper.Content step="account"><p>Account form</p></Stepper.Content>
            <Stepper.Content step="profile"><p>Profile form</p></Stepper.Content>
            <Stepper.Content step="done"><p>All done!</p></Stepper.Content>
          </div>
          <div className="mt-4 flex flex-wrap gap-2">
            {stepper.state.isLast ? (
              <button type="button" onClick={() => stepper.navigation.reset()}>
                Reset
              </button>
            ) : (
              <>
                <Stepper.Prev>Previous</Stepper.Prev>
                <Stepper.Next>Next</Stepper.Next>
              </>
            )}
          </div>
        </>
      )}
    </Stepper.Root>
  );
}

```

--------------------------------

### Stepper Step Lookup Example

Source: https://stepperize.vercel.app/docs/react/api-references/hook

Illustrates using lookup helpers to retrieve step objects by ID or index, and to find neighboring steps. Access these via `stepper.lookup`.

```javascript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { useStepper } = defineStepper(
  { id: "info", title: "Info" },
  { id: "review", title: "Review" },
  { id: "done", title: "Done" }
);

function LookupExample() {
  const stepper = useStepper();
  const step = stepper.lookup.get("review");
  const neighbors = stepper.lookup.getNeighbors(stepper.state.current.data.id);
  return (
    <p>Review: {step?.title ?? "not found"}; neighbors: {neighbors.prev?.id ?? "none"} → {neighbors.next?.id ?? "none"}</p>
  );
}

```

--------------------------------

### Stepper.Prev Button Examples

Source: https://stepperize.vercel.app/docs/react/api-references/primitives

Use Stepper.Prev for navigating to the previous step. It's automatically disabled on the first step. Custom click handlers and disabled states can be configured.

```jsx
{/* Default behavior */}
<Stepper.Prev>Previous</Stepper.Prev>
```

```jsx
{/* Custom disabled behavior */}
<Stepper.Prev>Back</Stepper.Prev>
```

```jsx
{/* Custom click handler */}
<Stepper.Prev onClick={() => {
  console.log("Going back");
  stepper.navigation.prev();
}}>
  Previous
</Stepper.Prev>
```

--------------------------------

### Vertical Stepper Example

Source: https://stepperize.vercel.app/docs/react/examples/basic

Implement a vertical stepper by passing orientation="vertical" to Stepper.Root and Stepper.List. This is suitable for processes that benefit from a top-to-bottom flow.

```jsx
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Stepper } = defineStepper(
  { id: "one", title: "Step 1" },
  { id: "two", title: "Step 2" },
  { id: "three", title: "Step 3" }
);

function Trigger({ children }: { children: React.ReactNode }) {
  return (
    <Stepper.Trigger className="border border-gray-300 bg-white px-2 py-1 text-sm data-[status=active]:bg-blue-100 dark:data-[status=active]:bg-blue-900/40">
      {children}
    </Stepper.Trigger>
  );
}

function VerticalLine() {
  return <div className="ml-3 h-3 w-px bg-gray-300 dark:bg-gray-600" />;
}

export function VerticalStepper() {
  return (
    <Stepper.Root orientation="vertical">
      {({ stepper }) => (
        <>
          <Stepper.List
            orientation="vertical"
            className="m-0 flex w-fit list-none flex-col items-stretch gap-0 p-0"
          >
            {stepper.state.all.map((step, index) => (
              <React.Fragment key={step.id}>
                <Stepper.Item step={step.id}>
                  <Trigger>
                    <Stepper.Title render={(props) => <span {...props}>{step.title}</span>} />
                  </Trigger>
                </Stepper.Item>
                {index < stepper.state.all.length - 1 && <VerticalLine />}
              </React.Fragment>
            ))}
          </Stepper.List>
          <div className="mt-4 min-h-10">
            {stepper.state.all.map((step) => (
              <Stepper.Content key={step.id} step={step.id}>
                <p>Content for {step.title}</p>
              </Stepper.Content>
            ))}
          </div>
          <div className="mt-4 flex flex-wrap gap-2">
            {stepper.state.isLast ? (
              <button type="button" onClick={() => stepper.navigation.reset()}>
                Reset
              </button>
            ) : (
              <>
                <Stepper.Prev>Back</Stepper.Prev>
                <Stepper.Next>Continue</Stepper.Next>
              </>
            )}
          </div>
        </>
      )}
    </Stepper.Root>
  );
}

```

--------------------------------

### Add Navigation Controls (next / prev / reset)

Source: https://stepperize.vercel.app/docs/react/examples/scoped

Implement navigation buttons using `stepper.state.isFirst`, `stepper.state.isLast`, and `stepper.navigation.next()`, `prev()`, `reset()`. This example shows conditional rendering for 'Back', 'Next', and 'Reset' buttons.

```javascript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Scoped, useStepper } = defineStepper(
  { id: "info", title: "Info" },
  { id: "review", title: "Review" },
  { id: "done", title: "Done" }
);

function StepNavigation() {
  const stepper = useStepper();
  return (
    <div>
      {stepper.state.isLast ? (
        <button type="button" onClick={() => stepper.navigation.reset()}>
          Reset
        </button>
      ) : (
        <div>
          {!stepper.state.isFirst && (
            <button type="button" onClick={() => stepper.navigation.prev()}>
              Back
            </button>
          )}
          <button type="button" onClick={() => stepper.navigation.next()}>
            Next
          </button>
        </div>
      )}
    </div>
  );
}
```

--------------------------------

### Implement onBeforeTransition Hook

Source: https://stepperize.vercel.app/docs/react/api-references/hook

Use `stepper.lifecycle.onBeforeTransition` to run logic before a step transition. Return `false` to cancel the transition. This example shows a confirmation dialog before navigating back.

```javascript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { useStepper } = defineStepper(
  { id: "first", title: "First" },
  { id: "second", title: "Second" }
);

function MyStepper() {
  const stepper = useStepper();
  React.useEffect(() => {
    const unsub = stepper.lifecycle.onBeforeTransition(async (ctx) => {
      if (ctx.direction === "prev" && !window.confirm("Go back?")) return false;
    });
    return () => unsub();
  }, [stepper]);
  return (
    <button type="button" onClick={() => stepper.navigation.next()} disabled={stepper.state.isLast}>
      Next
    </button>
  );
}
```

--------------------------------

### Define and Use a Complete Stepper Component

Source: https://stepperize.vercel.app/docs/react/api-references/primitives

This example demonstrates how to define a fully-typed stepper component using `defineStepper` and render it with a list, content, and navigation controls. It includes imports for React and the `defineStepper` function.

```jsx
import React from "react"
import { defineStepper } from "@stepperize/react"

const { Stepper, useStepper } = defineStepper(
  { id: "account", title: "Account", description: "Create your account" },
  { id: "profile", title: "Profile", description: "Set up your profile" },
  { id: "complete", title: "Complete", description: "All done!" }
);

function OnboardingStepper() {
  return (
    <Stepper.Root orientation="horizontal">
      {({ stepper }) => (
        <div className="stepper-container">
          {/* Step list */}
          <Stepper.List className="stepper-list">
            {stepper.state.all.map((step) => (
              <Stepper.Item
                key={step.id}
                step={step.id}
                className="stepper-item"
              >
                <Stepper.Trigger className="stepper-trigger">
                  <Stepper.Indicator className="stepper-indicator" />
                  <div className="stepper-text">
                    <Stepper.Title className="stepper-title">
                      {step.title}
                    </Stepper.Title>
                    <Stepper.Description className="stepper-description">
                      {step.description}
                    </Stepper.Description>
                  </div>
                </Stepper.Trigger>
                <Stepper.Separator className="stepper-separator" />
              </Stepper.Item>
            ))}
          </Stepper.List>

          {/* Step content */}
          <div className="stepper-content-container">
            <Stepper.Content step="account">
              <h2>Create Account</h2>
              <p>Enter your email and password</p>
            </Stepper.Content>

            <Stepper.Content step="profile">
              <h2>Set Up Profile</h2>
              <p>Tell us about yourself</p>
            </Stepper.Content>

            <Stepper.Content step="complete">
              <h2>All Done!</h2>
              <p>Your account is ready</p>
            </Stepper.Content>
          </div>

          {/* Navigation */}
          <Stepper.Actions className="stepper-actions">
            <Stepper.Prev className="stepper-prev">
              Previous
            </Stepper.Prev>
            <Stepper.Next className="stepper-next">
              {stepper.state.isLast ? "Finish" : "Next"}
            </Stepper.Next>
          </Stepper.Actions>
        </div>
      )}
    </Stepper.Root>
  );
}

```

--------------------------------

### Full Multi-Step Form with Stepperize and TanStack Form

Source: https://stepperize.vercel.app/docs/react/examples/forms

This is a complete example of a multi-step form. It defines schemas for each step, uses `defineStepper` to create the stepper context, and `useForm` for form management and validation. It handles navigation between steps and displays validation errors.

```jsx
"use client";

import { useForm } from "@tanstack/react-form";
import { z } from "zod";
import { defineStepper } from "@stepperize/react";

const PersonalSchema = z.object({
  name: z.string().min(1, "Name required"),
  email: z.email("Invalid email"),
});
const AddressSchema = z.object({
  street: z.string().min(1, "Street required"),
  city: z.string().min(1, "City required"),
});

const { Scoped, useStepper } = defineStepper(
  { id: "personal", title: "Personal", schema: PersonalSchema },
  { id: "address", title: "Address", schema: AddressSchema },
  { id: "done", title: "Done" }
);

type FormValues = { name: string; email: string; street: string; city: string };

function StepForm() {
  const stepper = useStepper();
  const stepData = stepper.state.current.data;
  const schema = "schema" in stepData && stepData.schema ? (stepData.schema as z.ZodType<FormValues>) : z.object({});

  const form = useForm<FormValues>({
    defaultValues: { name: "", email: "", street: "", city: "" },
    validators: { onChange: schema },
    onSubmit: ({ value }) => {
      if (!stepper.state.isLast) stepper.navigation.next();
    },
  });

  if (stepper.flow.is("done")) return <p>All done!</p>;

  return (
    <form onSubmit={(e) => { e.preventDefault(); e.stopPropagation(); form.handleSubmit(); }}>
      {stepper.flow.switch({
        personal: () => (
          <div>
            <form.Field name="name" children={(field) => (
              <div>
                <label htmlFor={field.name}>Name</label>
                <input id={field.name} name={field.name} value={field.state.value} onBlur={field.handleBlur} onChange={(e) => field.handleChange(e.target.value)} />
                {field.state.meta.isTouched && field.state.meta.errors?.length ? <em>{field.state.meta.errors.map((e) => (typeof e === "object" && e && "message" in e ? (e as { message: string }).message : String(e))).join(", ")}</em> : null}
              </div>
            )} />
            <form.Field name="email" children={(field) => (
              <div>
                <label htmlFor={field.name}>Email</label>
                <input id={field.name} name={field.name} type="email" value={field.state.value} onBlur={field.handleBlur} onChange={(e) => field.handleChange(e.target.value)} />
                {field.state.meta.isTouched && field.state.meta.errors?.length ? <em>{field.state.meta.errors.map((e) => (typeof e === "object" && e && "message" in e ? (e as { message: string }).message : String(e))).join(", ")}</em> : null}
              </div>
            )} />
          </div>
        ),
        address: () => (
          <div>
            <form.Field name="street" children={(field) => (
              <div>
                <label htmlFor={field.name}>Street</label>
                <input id={field.name} name={field.name} value={field.state.value} onBlur={field.handleBlur} onChange={(e) => field.handleChange(e.target.value)} />
                {field.state.meta.isTouched && field.state.meta.errors?.length ? <em>{field.state.meta.errors.map((e) => (typeof e === "object" && e && "message" in e ? (e as { message: string }).message : String(e))).join(", ")}</em> : null}
              </div>
            )} />
            <form.Field name="city" children={(field) => (
              <div>
                <label htmlFor={field.name}>City</label>
                <input id={field.name} name={field.name} value={field.state.value} onBlur={field.handleBlur} onChange={(e) => field.handleChange(e.target.value)} />
                {field.state.meta.isTouched && field.state.meta.errors?.length ? <em>{field.state.meta.errors.map((e) => (typeof e === "object" && e && "message" in e ? (e as { message: string }).message : String(e))).join(", ")}</em> : null}
              </div>
            )} />
          </div>
        ),
        done: () => null,
      })}
      <button type="submit">Next</button>
    </form>
  );
}

function StepNavigation() {
  const stepper = useStepper();
  return (
    <div>
      {!stepper.state.isFirst && <button type="button" onClick={() => stepper.navigation.prev()}>Back</button>}
      {stepper.state.isLast && <button type="button" onClick={() => stepper.navigation.reset()}>Reset</button>}
    </div>
  );
}

export function TanStackStepperForm() {
  return (
    <Scoped>
      <StepForm />
      <StepNavigation />
    </Scoped>
  );
}

```

--------------------------------

### Conform Stepper Form Example

Source: https://stepperize.vercel.app/docs/react/examples/forms

Integrates Stepperize with Conform for managing multi-step form state and validation. Use this for forms requiring complex validation logic handled by Conform.

```typescript
"use client";

import { getFormProps, useForm } from "@conform-to/react";
import { parseWithZod } from "@conform-to/zod/v4/future";
import { z } from "zod";
import { defineStepper } from "@stepperize/react";

const PersonalSchema = z.object({
  name: z.string().min(1, "Name required"),
  email: z.email("Invalid email"),
});
const AddressSchema = z.object({
  street: z.string().min(1, "Street required"),
  city: z.string().min(1, "City required"),
});

const { Scoped, useStepper } = defineStepper(
  { id: "personal", title: "Personal", schema: PersonalSchema },
  { id: "address", title: "Address", schema: AddressSchema },
  { id: "done", title: "Done" }
);

function StepForm() {
  const stepper = useStepper();
  const stepData = stepper.state.current.data;
  const schema = "schema" in stepData && stepData.schema ? stepData.schema : undefined;

  const [form, fields] = useForm({
    onValidate({ formData }) {
      return schema ? parseWithZod(formData, { schema }) : parseWithZod(formData, { schema: z.object({}) });
    },
    onSubmit(e, { formData }) {
      e.preventDefault();
      const result = schema ? parseWithZod(formData, { schema }) : parseWithZod(formData, { schema: z.object({}) });
      if (result.status === "success" && !stepper.state.isLast) stepper.navigation.next();
    },
  });

  if (stepper.flow.is("done")) return <p>All done!</p>;

  return (
    <form method="post" {...getFormProps(form)}>
      {stepper.flow.switch({
        personal: () => (
          <>
            <div><label>Name</label><input name={fields.name.name} /></div>
            <div><label>Email</label><input name={fields.email.name} type="email" /></div>
          </>
        ),
        address: () => (
          <>
            <div><label>Street</label><input name={fields.street.name} /></div>
            <div><label>City</label><input name={fields.city.name} /></div>
          </>
        ),
        done: () => null,
      })}
      <button type="submit">Next</button>
    </form>
  );
}

function StepNavigation() {
  const stepper = useStepper();
  return (
    <div>
      {!stepper.state.isFirst && <button type="button" onClick={() => stepper.navigation.prev()}>Back</button>}
      {stepper.state.isLast && <button type="button" onClick={() => stepper.navigation.reset()}>Reset</button>}
    </div>
  );
}

export function ConformStepperForm() {
  return (
    <Scoped>
      <StepForm />
      <StepNavigation />
    </Scoped>
  );
}

```

--------------------------------

### Stepper.Root Component

Source: https://stepperize.vercel.app/docs/react/api-references/scoped

Explains `Stepper.Root` as a convenience wrapper that internally uses `Scoped` and provides access to the stepper instance via a render prop. It simplifies initial state setup using `initialStep` and `initialMetadata`.

```APIDOC
## Stepper.Root Component

### Description
`Stepper.Root` is a component that wraps your stepper content and provides the stepper instance through a render prop. It internally utilizes the `Scoped` component and accepts `initialStep` and `initialMetadata` props to configure the initial state.

### Usage
```jsx
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Stepper, useStepper } = defineStepper(
  { id: "first", title: "First" },
  { id: "second", title: "Second" }
);

export const MyStepper = () => (
  <Stepper.Root>
    {({ stepper }) => (
      <div>
        <p>Current: {stepper.state.current.data.title}</p>
        <button onClick={() => stepper.navigation.next()}>Next</button>
      </div>
    )}
  </Stepper.Root>
);
```
```

--------------------------------

### Scoped Stepper with Initial State

Source: https://stepperize.vercel.app/docs/react/api-references/scoped

Configure the initial step and metadata for a stepper using the `initialStep` and `initialMetadata` props on the Scoped component. This sets the starting point and pre-defined states for your stepper.

```jsx
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Scoped, useStepper } = defineStepper(
  { id: "first", title: "First" },
  { id: "second", title: "Second" },
  { id: "last", title: "Last" }
);

export const MyScopedStepper = () => (
  <Scoped
    initialStep="second"
    initialMetadata={{ first: { completed: true }, second: null, last: null }}
  >
    <StepContent />
  </Scoped>
);

const StepContent = () => {
  const stepper = useStepper();
  return <div>Current: {stepper.state.current.data.title}</div>;
};

```

--------------------------------

### Manage Step Metadata with set, get, and reset

Source: https://stepperize.vercel.app/docs/react/api-references/hook

Use `stepper.metadata.set(id, values)` to save metadata for a specific step, `stepper.metadata.get(id)` to retrieve it, and `stepper.metadata.reset(keepInitialMetadata?)` to clear it. You can also manage metadata for the current step directly.

```javascript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { useStepper } = defineStepper(
  { id: "first", title: "First step" },
  { id: "second", title: "Second step" },
  { id: "last", title: "Last step" }
);

const MyStepperComponent = () => {
  const stepper = useStepper();
  const handleSave = () => {
    stepper.metadata.set("first", { value: "saved" });
  };
  const meta = stepper.metadata.get("first");
  return (
    <div>
      <button type="button" onClick={handleSave}>Save</button>
      <p>First step: {meta?.value}</p>
      <button type="button" onClick={() => stepper.metadata.reset(true)}>Reset metadata</button>
    </div>
  );
};

```

--------------------------------

### Add Stepper with Description (Base UI)

Source: https://stepperize.vercel.app/docs/react/shadcn

Use this command to add a stepper component that includes descriptions for each step, using Base UI.

```bash
npx shadcn add https://stepperize.vercel.app/r/base-ui/stepper-with-description.json
```

--------------------------------

### Get Namespace Type Utilities

Source: https://stepperize.vercel.app/docs/react/api-references/types

Illustrates how to use the Get namespace for type inference of step IDs and step types based on a Steps array.

```typescript
import { defineStepper, Get } from "@stepperize/react";

const { steps } = defineStepper(
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" }
);

type StepId = Get.Id<typeof steps>;           // "shipping" | "payment"
type ShippingStep = Get.StepById<typeof steps, "shipping">;  // { id: "shipping"; title: string }
```

--------------------------------

### Use Stepper with Initial Configuration (v5)

Source: https://stepperize.vercel.app/docs/react/migration/migrating-to-v5

When migrating to v5, the `useStepper` hook now expects an object with an `initial` property for configuration. This object includes `step`, `metadata`, and `statuses` for the initial state.

```javascript
const methods = useStepper({
  initial: {
    step: "first",        // The ID of the initial step to display
    metadata: { ... },    // The initial metadata for each step
    statuses: { ... },    // The initial status for each step
  }
});
```

--------------------------------

### Add Stepper with Description (Radix UI)

Source: https://stepperize.vercel.app/docs/react/shadcn

Use this command to add a stepper component that includes descriptions for each step, using Radix UI.

```bash
npx shadcn add https://stepperize.vercel.app/r/radix-ui/stepper-with-description.json
```

--------------------------------

### Wrap with Stepper.Root

Source: https://stepperize.vercel.app/docs/react/examples/basic

Use Stepper.Root to initialize the stepper component with the defined steps.

```javascript
<Stepper.Root steps={steps}>
  {/* ... stepper content ... */}
</Stepper.Root>
```

--------------------------------

### Get Namespace Types

Source: https://stepperize.vercel.app/docs/react/api-references/types

Utility types for inferring information about steps based on their IDs and the overall Steps type.

```APIDOC
## Get namespace

Type| Description  
---|---
`Get.Id<Steps>`| Union of step IDs  
`Get.StepById<Steps, Id>`| Step type for given ID  
`Get.StepSansId<Steps, Id>`| Union of steps that are not `Id`  
`Get.Switch<Steps, R>`| Object type for `flow.switch` handlers: `{ [Id in Get.Id<Steps>]?: (step: Get.StepById<Steps, Id>) => R }`  

```typescript
import { defineStepper, Get } from "@stepperize/react";

const { steps } = defineStepper(
  { id: "shipping", title: "Shipping" },
  { id: "payment", title: "Payment" }
);

type StepId = Get.Id<typeof steps>;           // "shipping" | "payment"
type ShippingStep = Get.StepById<typeof steps, "shipping">;  // { id: "shipping"; title: string }
```
```

--------------------------------

### useStepper Configuration: Initial State (v5 vs v6)

Source: https://stepperize.vercel.app/docs/react/migration/migrating-to-v6

v5 used a nested `initial` object for step, metadata, and statuses. v6 uses top-level `initialStep` and `initialMetadata`, and statuses are derived.

```javascript
useStepper({
  initial: {
    step: "second",
    metadata: { first: { saved: true } },
    statuses: { ... },
  },
});
```

```javascript
useStepper({
  initialStep: "second",
  initialMetadata: { first: { saved: true } },
});
```

--------------------------------

### Custom Step Indicator with Step Index

Source: https://stepperize.vercel.app/docs/react/examples/basic

Customize the indicator for each step by providing a render prop to `Stepper.Indicator`. This example shows how to display the step index.

```javascript
<Stepper.Item key={step.id} step={step.id}>
  <Stepper.Indicator>
    {({ index }) => <span>{index + 1}</span>}
  </Stepper.Indicator>
  <Stepper.Label>{step.label}</Stepper.Label>
</Stepper.Item>
```

--------------------------------

### Add Stepper with Icons (Base UI)

Source: https://stepperize.vercel.app/docs/react/shadcn

Use this command to add a stepper component that includes icons for each step, using Base UI.

```bash
npx shadcn add https://stepperize.vercel.app/r/base-ui/stepper-with-icon.json
```

--------------------------------

### Use Stepper Hook

Source: https://stepperize.vercel.app/docs/react/api-references/hook

Use the useStepper hook to access the stepper instance and its API for state management and navigation. This example shows basic usage within a component.

```javascript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { useStepper } = defineStepper(
  { id: "first", title: "First step" },
  { id: "second", title: "Second step" }
);

const MyStepperComponent = () => {
  const stepper = useStepper();
  return (
    <div>
      <h1>{stepper.state.current.data.title}</h1>
      <button onClick={() => stepper.navigation.next()} disabled={stepper.state.isLast}>Next</button>
      <button onClick={() => stepper.navigation.prev()} disabled={stepper.state.isFirst}>Previous</button>
    </div>
  );
};

```

--------------------------------

### Stepper.Next Button Examples

Source: https://stepperize.vercel.app/docs/react/api-references/primitives

Use Stepper.Next for navigating to the next step. It's automatically disabled on the last step. Dynamic labels and custom click handlers with validation are supported.

```jsx
{/* Default behavior */}
<Stepper.Next>Next</Stepper.Next>
```

```jsx
{/* Dynamic label */}
<Stepper.Next>
  {stepper.state.isLast ? "Finish" : "Next"}
</Stepper.Next>
```

```jsx
{/* Custom click with validation */}
<Stepper.Next onClick={async () => {
  const isValid = await validateCurrentStep();
  if (isValid) {
    stepper.navigation.next();
  }
}}>
  Continue
</Stepper.Next>
```

--------------------------------

### Stepper Separator with Dynamic Rendering

Source: https://stepperize.vercel.app/docs/react/api-references/primitives

Implement Stepper.Separator to visually divide steps. This example shows how to conditionally render the separator between items in a Stepper.List, ensuring the last separator is not displayed.

```jsx
<Stepper.List>
  {stepper.state.all.map((step, index) => (
    <React.Fragment key={step.id}>
      <Stepper.Item step={step.id}>
        <Stepper.Trigger>...</Stepper.Trigger>
      </Stepper.Item>
      {index < stepper.state.all.length - 1 && <Stepper.Separator />}
    </React.Fragment>
  ))}
</Stepper.List>
```

--------------------------------

### Configure Initial Step and Metadata

Source: https://stepperize.vercel.app/docs/react/examples/scoped

Set the initial step and initial metadata for a stepper by passing `initialStep` and `initialMetadata` props to the `Scoped` component. This allows pre-populating state for specific steps.

```javascript
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Scoped, useStepper } = defineStepper(
  { id: "info", title: "Info" },
  { id: "review", title: "Review" },
  { id: "done", title: "Done" }
);

function StepContent() {
  const stepper = useStepper();
  return <div>{/* content per step */}</div>;
}

function StepNavigation() {
  const stepper = useStepper();
  return <div>{/* buttons */}</div>;
}

function Example() {
  return (
    <Scoped
      initialStep="review"
      initialMetadata={{ info: { name: "Jane" } }}
    >
      <StepContent />
      <StepNavigation />
    </Scoped>
  );
}
```

--------------------------------

### Add Stepper with Icons (Radix UI)

Source: https://stepperize.vercel.app/docs/react/shadcn

Use this command to add a stepper component that includes icons for each step, using Radix UI.

```bash
npx shadcn add https://stepperize.vercel.app/r/radix-ui/stepper-with-icon.json
```

--------------------------------

### Stepper.Root for Context Provision

Source: https://stepperize.vercel.app/docs/react/api-references/scoped

Utilize `Stepper.Root` as a convenient wrapper that internally uses `Scoped` to provide stepper context. It accepts `initialStep` and `initialMetadata` for setting initial state, offering an alternative to directly using `Scoped`.

```jsx
import React from "react";
import { defineStepper } from "@stepperize/react";

const { Stepper, useStepper } = defineStepper(
  { id: "first", title: "First" },
  { id: "second", title: "Second" }
);

export const MyStepper = () => (
  <Stepper.Root>
    {({ stepper }) => (
      <div>
        <p>Current: {stepper.state.current.data.title}</p>
        <button onClick={() => stepper.navigation.next()}>Next</button>
      </div>
    )}
  </Stepper.Root>
);

```
Tokens:
Raw