Navigation@knitui/components

Stepper

Stepper guides users through a multi-step flow. Compose Stepper.Step children for each step and an optional Stepper.Completed for the finished state. active controls the current position; onStepClick enables navigation between steps. orientation flips the layout to vertical, iconPosition mirrors the bubble to the right, and keepMounted preserves step state across navigation.

WebiOSAndroid8 style slots14 own props16 examples

Stories Source Tests Open in Storybook

import { Stepper } from "@knitui/components";

Playground

Loading playground…

activeIndex of the currently active step.

sizeControls bubble diameter, connector thickness and font sizes.

themeAccent theme used for progress and completed steps.

orientationLayout axis of the step row.

variantVisual mode: numbered bubbles + content panel (stepper) or filled-dot bullets with inline content (timeline).

iconPositionPosition of the step bubble relative to the label body.

allowNextStepsSelectAllow clicking steps after the active one.

true

keepMountedKeep all step content mounted (hidden with display:none) to preserve state.

false

wrapWrap the horizontal step row when it overflows.

true

Playground

<Stepper
  active={1}
  size="md"
  orientation="horizontal"
  iconPosition="left"
  allowNextStepsSelect
  keepMounted={false}
  wrap
/>

Examples

Sizes

All seven sizes from xxs to xxl.

Loading example…

SizesSource Storybook

Theme

Accent color follows Tamagui's theme prop.

Loading example…

ThemeSource Storybook

Vertical

Vertical orientation — steps stack top to bottom with the connector on the left.

Loading example…

VerticalSource Storybook

Shadows

Elevation shadow ladder applied to the Stepper frame via the inherited shadow prop.

Loading example…

ShadowsSource Storybook

Controlled

Controlled stepper — the parent owns active and wires navigation buttons.

Loading example…

ControlledSource Storybook

With Completed

Stepper.Completed is shown when active is past the last step index.

Loading example…

With CompletedSource Storybook

Loading Step

A loading step shows a spinner inside the bubble instead of the step number.

Loading example…

Loading StepSource Storybook

Custom Icons

Custom icons and completedIcon per step using unicode glyphs.

Loading example…

Custom IconsSource Storybook

Keep Mounted

keepMounted preserves all step content in the DOM — useful for uncontrolled forms.

Loading example…

Keep MountedSource Storybook

Timeline Vertical

Timeline variant — filled-dot bullets with each step's content inline (the former Timeline component), here vertical.

Loading example…

Timeline VerticalSource Storybook

Timeline Horizontal

The timeline variant also lays out horizontally.

Loading example…

Timeline HorizontalSource Storybook

Timeline Line Variants

Per-step lineVariant makes the connector solid, dashed, or dotted (timeline only).

Loading example…

Timeline Line VariantsSource Storybook

Timeline Custom Bullets

Custom bullets — pass any node (icon, number, emoji) via a step's icon.

Loading example…

Timeline Custom BulletsSource Storybook

Timeline Reverse Active

reverseActive counts completed steps from the end, so the last step completes first.

Loading example…

Timeline Reverse ActiveSource Storybook

Styles

Per-slot styles targets individual parts — here the bubble, label and connector.

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`active` required	`number`	`1`	Index of the currently active step.
`children` required	`ReactNode`	—	`Stepper.Step` / `Stepper.Completed` children.
`allowNextStepsSelect`	`boolean \| undefined`	`true`	Allow clicking steps after the active one.
`completedIcon`	`ReactNode \| StepFragmentComponent`	—	Default completed icon for every step. Accepts a render fn `({ step }) => node`.
`contentPadding`	`number \| SpaceTokens \| Animated.AnimatedNode \| "safe" \| null \| undefined`	`'$md'`	Padding around the active step's content.
`disabled` system	`boolean \| undefined`	—
`icon`	`ReactNode \| StepFragmentComponent`	—	Default icon for every step (overridable per step). Accepts a render fn `({ step }) => node`.
`iconPosition`	`StepperIconPosition \| undefined` left · right	`'left'`	Position of the step bubble relative to the label body.
`iconSize`	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—	Override the step-bubble diameter (independent of `size`).
`keepMounted`	`boolean \| undefined`	`false`	Keep all step content mounted (hidden with display:none) to preserve state.
`onStepClick`	`((index: number) => void) \| undefined`	—	Called with the 0-based index of a clicked, selectable step.
`orientation`	`StepperOrientation \| undefined` horizontal · vertical	`'horizontal'`	Layout axis of the step row.
`progressIcon`	`ReactNode \| StepFragmentComponent`	—	Default progress icon for every step. Accepts a render fn `({ step }) => node`.
`radius` system	`string \| number \| undefined`	`circular`	Bubble border radius.
`reverseActive`	`boolean \| undefined`	`false`	Count the active progression from the LAST step instead of the first, so the bottom/end step completes first (former Timeline `reverseActive`).
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—
`size` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` xxs · xs · sm · md · lg · xl · xxl	`'md'`	Controls bubble diameter, connector thickness and font sizes.
`styles` system	`SlotStyles<StepperStyles> \| undefined`	—	Per-slot style sugar — props spread onto every step's parts + the connector.
`theme` system	`ThemeName \| null \| undefined` unset · blue · red · green · yellow · pink · gray	—	Accent theme used for progress and completed steps.
`variant` system	`StepperVariant \| undefined` stepper · timeline	`'stepper'`	Visual mode: numbered bubbles + content panel (stepper) or filled-dot bullets with inline content (timeline).
`wrap`	`boolean \| undefined`	`true`	Wrap the horizontal step row when it overflows.

Style slots

Every part of Stepper can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`bubble`	`styles={{ bubble: { … } }}`
`bubbleText`	`styles={{ bubbleText: { … } }}`
`connector`	`styles={{ connector: { … } }}`
`content`	`styles={{ content: { … } }}`
`description`	`styles={{ description: { … } }}`
`label`	`styles={{ label: { … } }}`
`step`	`styles={{ step: { … } }}`
`steps`	`styles={{ steps: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 497 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.