## Overview [#overview] The `Stepper` component guides users through sequential steps with separate selection and status states. A step can be inactive, active, or disabled while also using the incomplete, completed, or loading status. Previous and current steps are progress-colored separately from the status icon. It supports horizontal and vertical layouts, controlled and uncontrolled values, animated step content, and optional URL state. Stepper indicators are surface-aware. Unreached indicators land two levels above the parent surface with the matching contextual border. Reached indicators use the brand fill, while status controls whether the marker shows a number, check icon, or spinner. Hovering a step increases the indicator and the wrapper around the title/description without requiring local color overrides. ## Usage [#usage] ```tsx import { Stepper, StepperDescription, StepperHeading, StepperIndicator, StepperItem, StepperSeparator, StepperTitle, StepperTrigger, } from "@tilt-legal/cubitt-components/stepper"; ``` ```tsx Account Create your account Profile Add your profile details ``` ## URL State [#url-state] Provide `paramName` to sync the active step with the current URL. ```tsx Account Profile Complete ``` ## Examples [#examples] ### States [#states] Toggle one centered step through selection state and status. ```tsx import { useState } from "react"; import { Stepper, StepperDescription, StepperHeading, StepperIndicator, StepperItem, StepperTitle, StepperTrigger, } from "@tilt-legal/cubitt-components/stepper"; import { ToggleGroup, ToggleGroupItem, } from "@tilt-legal/cubitt-components/toggle-group"; type SelectionState = "inactive" | "active" | "disabled"; type Status = "incomplete" | "completed" | "loading"; const selectionStates = ["inactive", "active", "disabled"] as const; const statuses = ["incomplete", "completed", "loading"] as const; const [selectionState, setSelectionState] = useState("active"); const [status, setStatus] = useState("incomplete"); const activeStep = selectionState === "active" ? 1 : 0; <> {`${selectionState[0]?.toUpperCase()}${selectionState.slice(1)}`} {`${status[0]?.toUpperCase()}${status.slice(1)} status`} { if (selectionStates.includes(value as SelectionState)) { setSelectionState(value as SelectionState); } }} value={selectionState} > Inactive Active Disabled { if (statuses.includes(value as Status)) { setStatus(value as Status); } }} value={status} > Incomplete Completed Loading ; ``` ### Basic [#basic] ```tsx {[1, 2, 3].map((step) => ( {`Step ${step}`} {`Description for step ${step}`} {step < 3 && ( )} ))} ``` ### Vertical [#vertical] ```tsx {[1, 2, 3].map((step) => ( {`Step ${step}`} {`Description for step ${step}`} {step < 3 && ( )} ))} ``` ### Mixed Elements [#mixed-elements] ```tsx import { Avatar, AvatarFallback } from "@tilt-legal/cubitt-components/avatar"; import { Shuffle } from "@tilt-legal/cubitt-icons/ui/outline"; M ``` ### Progress Bar [#progress-bar] ```tsx {[1, 2, 3, 4].map((step) => ( {step} {`Step ${step}`} ))} ``` ### URL State [#url-state-1] ```tsx {[ { step: 1, title: "Account", description: "Create your account" }, { step: 2, title: "Profile", description: "Setup your profile" }, { step: 3, title: "Settings", description: "Configure settings" }, ].map(({ step, title, description }) => ( {step} {title} {description} ))} ``` ### Animated Content [#animated-content] ```tsx const [showContent, setShowContent] = useState(false); <> {[1, 2, 3].map((step) => ( {step === 2 ? "Review Details" : `Step ${step}`} Verify information {step === 2 && showContent && (

Review the uploaded materials before continuing.

The step body can hold supporting copy, form fields, or actions.

When hidden, the layout collapses around the stepper controls.

)} {step < 3 && ( )} ))} ; ``` ## API Reference [#api-reference] ### Stepper [#stepper] The root component owns active-step state and orientation. It does not add a surface of its own. | Prop | Type | Default | Description | | ---------------- | -------------------------------------- | -------------- | ------------------------------------------------------ | | `defaultValue` | `number` | `0` | The initial active step when uncontrolled. | | `value` | `number` | - | Controlled active step value. | | `onValueChange` | `(value: number) => void` | - | Called when the active step changes. | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Stepper layout direction. | | `animateContent` | `boolean` | `false` | Animates non-trigger `StepperItem` content in and out. | | `className` | `string` | - | Additional classes for layout and sizing. | | `...props` | `React.HTMLAttributes` | - | Standard `div` attributes. | ### URL State Props [#url-state-props] | Prop | Type | Default | Description | | --------------------- | --------------------------------- | ------- | ------------------------------------------------------------- | | `paramName` | `string` | - | URL parameter name for syncing the step. | | `paramValue` | `number` | - | Controlled value for URL state. | | `onUrlValueChange` | `(value: number \| null) => void` | - | Called when the URL value changes. | | `paramClearOnDefault` | `boolean` | `true` | Removes the URL parameter when the value matches the default. | | `paramThrottle` | `number` | - | Throttle window for URL updates. | | `paramDebounce` | `number` | - | Debounce window for URL updates. | ### StepperItem [#stepperitem] Container for one step. It provides selection state and status to its trigger, indicator, heading, title, description, and separator. | Prop | Type | Default | Description | | ----------- | -------------------------------------- | ------- | -------------------------------------------------------------------------------------------- | | `step` | `number` | - | Step value for this item. | | `completed` | `boolean` | `false` | Sets the item status to completed. This can combine with inactive or active selection state. | | `disabled` | `boolean` | `false` | Disables the step trigger. | | `loading` | `boolean` | `false` | Sets the item status to loading. This can combine with inactive or active selection state. | | `className` | `string` | - | Additional classes for the item. | | `...props` | `React.HTMLAttributes` | - | Standard `div` attributes. | ### StepperTrigger [#steppertrigger] Interactive control that activates its step. | Prop | Type | Default | Description | | ----------- | ----------------------------------------------- | ------- | ---------------------------------------- | | `render` | `ReactElement` | - | Custom element to render as the trigger. | | `className` | `string` | - | Additional classes for trigger layout. | | `...props` | `React.ButtonHTMLAttributes` | - | Standard button attributes. | ### StepperIndicator [#stepperindicator] Visual step marker. Unreached indicators are surface-aware; reached indicators use the brand fill. Status controls whether the marker shows the step number, check icon, or spinner. | Prop | Type | Default | Description | | ----------- | --------------------------------------- | ------- | -------------------------------------------------------------------------- | | `children` | `ReactNode` | - | Custom indicator content. Defaults to step number, check icon, or spinner. | | `className` | `string` | - | Additional classes for shape and size. | | `...props` | `React.HTMLAttributes` | - | Standard `span` attributes. | ### StepperHeading [#stepperheading] Wrapper for step title and description content. It receives the shared hover background from the step trigger and the active selection background when its step is active. | Prop | Type | Default | Description | | ----------- | -------------------------------------- | ------- | ------------------------------------------------------ | | `className` | `string` | - | Additional classes for layout, alignment, and spacing. | | `...props` | `React.HTMLAttributes` | - | Standard `div` attributes. | ### StepperTitle [#steppertitle] Title text for the step. Use it inside `StepperHeading` when title and description should share one interaction background. | Prop | Type | Default | Description | | ----------- | ------------------------------------------ | ------- | --------------------------------- | | `className` | `string` | - | Additional classes for the title. | | `...props` | `React.HTMLAttributes` | - | Standard heading attributes. | ### StepperDescription [#stepperdescription] Supporting text for the step. Use it inside `StepperHeading` with `StepperTitle`. | Prop | Type | Default | Description | | ----------- | -------------------------------------------- | ------- | --------------------------------------- | | `className` | `string` | - | Additional classes for the description. | | `...props` | `React.HTMLAttributes` | - | Standard paragraph attributes. | ### StepperSeparator [#stepperseparator] Connector between steps. Separators for previous steps use the brand fill; pending separators use the contextual border color one level above the parent surface. | Prop | Type | Default | Description | | ----------- | -------------------------------------- | ------- | ------------------------------------------------------- | | `className` | `string` | - | Additional classes for position, length, and thickness. | | `...props` | `React.HTMLAttributes` | - | Standard `div` attributes. |