Onboarding Pager

Pro

Swipeable first-run pages with Skip, page dots or a progress bar, and a Continue button that becomes Get started. Each page’s artwork brightens once you land on it.

Preview

Installation

npx @lumioui/cli add pro/onboarding-pager

Usage

import { useOnboardingPageActive, OnboardingPager } from "@/components/ui/onboarding-pager/onboarding-pager";
<OnboardingPager />

Also exported: useOnboardingPageActive.

Examples

Budget

A budgeting app's first run, lit from above in green.

Fitness setup

A training app's setup.

Full-bleed photo

A travel app's first run over full-bleed photos.

API reference

OnboardingPage

Prop Type Default
title* string

Headline — sentence case, 4–7 words.

 —
description string

One or two lines under the headline.

 —
art React.ReactNode

Hero art — illustration, product shot, or a composed UI fragment. Parallaxes.

 —
background React.ReactNode

Full-bleed layer behind the page (a photo + scrim). Parallaxes gently.

 —
align "center" | "bottom"

Where the copy sits. "center" under the art, "bottom" over a full-bleed photo. Default "center".

 —
children React.ReactNode

Extra content under the description (a permission toggle, a plan picker).

 —
className string —

OnboardingPager

Prop Type Default
children* React.ReactNode

OnboardingPager.Page elements (any element works as a page).

 —
index number

Controlled page index (0-based).

 —
defaultIndex number

Uncontrolled initial page. Default 0.

 —
onIndexChange (index: number) => void

Fires when a page settles.

 —
onDone () => void | Promise<unknown>

Called by the last page's button. May return a promise — busy dots hold the label's place until it settles.

 —
doneSuccessLabel string

What the last button becomes once onDone resolves ("Connected · 2 accounts"). It holds as the result; omit to return to doneLabel.

 —
light boolean

Light the stage from above in the accent hue. Default true (off for tone="inverse").

 —
onSkip () => void

Called by Skip. Default: jump to the last page.

 —
showSkip boolean

Show the Skip button. Default true.

 —
skipLabel string

Default "Skip".

 —
nextLabel string

Default "Continue".

 —
doneLabel string

Default "Get started".

 —
indicator "dots" | "bar" | "none"

"dots" — stretching pill dots. "bar" — segmented progress bar at the top. "none". Default "dots".

 —
tone "default" | "inverse"

"inverse" sets white copy, white dots and a white CTA for full-bleed photo pages.

 —
footer React.ReactNode

Content under the button — "I already have an account".

 —
className string —