Onboarding Dialog

ProNew

A multi-step dialog for tours and announcements with a media area, direction-aware transitions, step dots and arrow key paging.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.


pnpm dlx shadcn@latest add @tealmac-pro/onboarding-dialog

To show the tour on first visit, control it: open={!seen} and onOpenChange.

Prop	Type	Default	Description
`steps`	`OnboardingStep[]`	-	Pages, each with `title`, optional `description` and `media`.
`trigger`	`ReactNode`	-	Element that opens the dialog (rendered with `asChild`).
`open`	`boolean`	-	Open state when controlled.
`defaultOpen`	`boolean`	`false`	Open on first render when uncontrolled.
`onOpenChange`	`(open: boolean) => void`	-	Called when the dialog opens or closes.
`step`	`number`	-	Current step when controlled.
`defaultStep`	`number`	`0`	Step shown each time the dialog opens.
`onStepChange`	`(step: number) => void`	-	Called when the step changes.
`onComplete`	`() => void`	-	Called by the last step's button, before closing.
`onSkip`	`(step: number) => void`	-	Called by Skip, Escape or an outside click.
`backLabel`	`string`	`"Back"`	Back button text.
`nextLabel`	`string`	`"Next"`	Next button text.
`finishLabel`	`string`	`"Get started"`	Last step button text.
`skipLabel`	`string`	`"Skip"`	Skip button text.
`className`	`string`	-	Classes for the dialog panel.
`ref`	`Ref<HTMLDivElement>`	-	Ref to the dialog panel.

Built on the shadcn/ui Dialog (Radix): focus is trapped, Escape closes, and focus returns to the trigger.
The current step's title and description name and describe the dialog. Outgoing text during a transition is hidden from assistive tech, so ids never repeat.
"Step 2 of 4" is a polite live region, so paging is announced.
Left and Right arrow keys page through the steps (ignored while typing in a field). Step dots are buttons named "Go to step N", and the current one has aria-current="step".
Steps slide and blur in the direction of travel; with reduced motion they cross-fade.

Guide and examples


pnpm dlx shadcn@latest add @tealmac-pro/onboarding-dialog

To show the tour on first visit, control it: open={!seen} and onOpenChange.

Prop	Type	Default	Description
`steps`	`OnboardingStep[]`	-	Pages, each with `title`, optional `description` and `media`.
`trigger`	`ReactNode`	-	Element that opens the dialog (rendered with `asChild`).
`open`	`boolean`	-	Open state when controlled.
`defaultOpen`	`boolean`	`false`	Open on first render when uncontrolled.
`onOpenChange`	`(open: boolean) => void`	-	Called when the dialog opens or closes.
`step`	`number`	-	Current step when controlled.
`defaultStep`	`number`	`0`	Step shown each time the dialog opens.
`onStepChange`	`(step: number) => void`	-	Called when the step changes.
`onComplete`	`() => void`	-	Called by the last step's button, before closing.
`onSkip`	`(step: number) => void`	-	Called by Skip, Escape or an outside click.
`backLabel`	`string`	`"Back"`	Back button text.
`nextLabel`	`string`	`"Next"`	Next button text.
`finishLabel`	`string`	`"Get started"`	Last step button text.
`skipLabel`	`string`	`"Skip"`	Skip button text.
`className`	`string`	-	Classes for the dialog panel.
`ref`	`Ref<HTMLDivElement>`	-	Ref to the dialog panel.

Built on the shadcn/ui Dialog (Radix): focus is trapped, Escape closes, and focus returns to the trigger.
The current step's title and description name and describe the dialog. Outgoing text during a transition is hidden from assistive tech, so ids never repeat.
"Step 2 of 4" is a polite live region, so paging is announced.
Left and Right arrow keys page through the steps (ignored while typing in a field). Step dots are buttons named "Go to step N", and the current one has aria-current="step".
Steps slide and blur in the direction of travel; with reduced motion they cross-fade.