# Onboarding > Composable multi-step onboarding for React and shadcn/ui with a step indicator, feature carousel, choice group, and tips list. Source: https://www.cult-ui.com/docs/components/onboarding ## Example ```tsx title="onboarding-demo.tsx" "use client" import { useState } from "react" import Image from "next/image" import { ArrowLeft, BookOpen, Building, Building2, CircleDashed, Code2, Download, Megaphone, Palette, Rocket, TrendingUp, } from "lucide-react" import { cn } from "@/lib/utils" import { Button } from "@/components/ui/button" import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, } from "@/components/ui/dialog" import { ChoiceGroup, FeatureCarousel, Onboarding, TipsList, useOnboarding, } from "../ui/onboarding" const STEP_CONFIG = [ { title: "Welcome to AI SDK Agents", description: "Start shipping ai agents that actually work.", }, { title: "Personalize your experience", description: "Tell us about yourself so we can tailor the experience", }, { title: "You're ready to go!", description: "A few tips to get the most out of AI SDK Agents", }, ] export const FEATURES = [ { id: "source-code", icon: Code2, // swap Sparkles → Code2 title: "Full Stack Source Code", description: "Browse and copy the complete source code for every pattern directly from the Source Code tab.", image: "/component-images/onboarding/onboarding-source-code.png", }, { id: "skills", icon: BookOpen, // swap ImagePlus → BookOpen (or similar) title: "Copy Skills & Critical Files", description: "Copy agent skills and critical files to supercharge your AI-powered workflows.", image: "/component-images/onboarding/onboarding-skills.png", }, { id: "download", icon: Download, // swap Lightbulb → Download title: "Download as Next.js App", description: "Download any pattern as a fully working Next.js application, ready to run locally.", image: "/component-images/onboarding/onboarding-nextjs.png", }, ] as const export const ROLES = [ { id: "designer", label: "Designer", icon: Palette }, { id: "founder", label: "Founder", icon: Rocket }, { id: "sales", label: "Sales", icon: TrendingUp }, { id: "freelancer", label: "Freelancer", icon: Building2 }, { id: "marketing", label: "Marketing", icon: Megaphone }, { id: "developer", label: "Developer", icon: Code2 }, { id: "agency", label: "Agency", icon: Building }, { id: "other", label: "Other", icon: CircleDashed }, ] as const export const GOALS = [ { id: "ai-agents", label: "Building AI agents" }, { id: "chatbots", label: "Chatbots & assistants" }, { id: "automation", label: "Workflow automation" }, { id: "rag", label: "RAG & search" }, { id: "prototyping", label: "Rapid prototyping" }, { id: "other", label: "Something else" }, ] as const export const TIPS = [ { number: 1, text: "Browse patterns by use case to find the right agent architecture for your project.", }, { number: 2, text: "Use the Download as Next.js App button to get a fully working local project in seconds.", }, { number: 3, text: "Copy skills and critical files to quickly skill up claude code and cursor.", }, ] as const export const TOTAL_STEPS = 3 export const MAX_STEP_VALUE = FEATURES.length - 1 // ============================================================================ // Headless Primitives Demo (composable, uses shadcn tokens) // ============================================================================ export default function OnboardingDemo() { return } export function HeadlessOnboardingDemo() { const [open, setOpen] = useState(false) const [selectedRole, setSelectedRole] = useState(null) const [selectedGoal, setSelectedGoal] = useState(null) return (
step === 1 || (step === 2 && selectedGoal !== null) || step === 3 } className="relative overflow-hidden" maxStepValue={MAX_STEP_VALUE} onComplete={() => setOpen(false)} totalSteps={3} >
) } function HeadlessOnboardingHeader() { const { currentStep } = useOnboarding() const config = STEP_CONFIG[currentStep - 1] return ( {/* */} {config.title} {config.description}
) } function HeadlessFeatureStep() { const { stepValue, setStepValue } = useOnboarding() return (
{FEATURES.map((feature, index) => { const Icon = feature.icon const isActive = stepValue === index return (

{feature.title}

{isActive && (

{feature.description}

)}
) })}
{FEATURES[stepValue].title}
) } function HeadlessRoleStep({ selectedRole, onRoleSelect, selectedGoal, onGoalSelect, }: { selectedRole: string | null onRoleSelect: (v: string) => void selectedGoal: string | null onGoalSelect: (v: string) => void }) { const { handleNext } = useOnboarding() const [question, setQuestion] = useState(selectedGoal ? 2 : 1) return (
{question === 1 ? (
1 What best describes you?
{ onRoleSelect(v) setTimeout(() => setQuestion(2), 300) }} orientation="grid" value={selectedRole} > {ROLES.map((role) => { const Icon = role.icon const isSelected = selectedRole === role.id return ( {role.label} ) })}

Question 1 of 2

) : (
2 What do you want to create?
{ onGoalSelect(v) setTimeout(() => handleNext(), 300) }} orientation="grid" value={selectedGoal} > {GOALS.map((goal) => { const isSelected = selectedGoal === goal.id return ( {goal.label} ) })}

Question 2 of 2

)}
) } function HeadlessTipsStep() { return (
{TIPS.map((tip) => (

{tip.text}

))}
Onboarding
) } ``` Onboarding is a set of composable React primitives for shadcn/ui. Use it for signup, first-run setup, or account personalization screens in SaaS apps. ## Installation ### CLI ```bash npx shadcn@latest add @cult-ui/onboarding ``` ### Manual **Copy and paste the following code into your project.** ```tsx title="onboarding.tsx" "use client" import type * as React from "react" import { Children, createContext, useCallback, useContext, useId, useMemo, type PropsWithChildren, } from "react" import { useControllableState } from "@radix-ui/react-use-controllable-state" import { cva, type VariantProps } from "class-variance-authority" import { cn } from "@/lib/utils" import { Button } from "@/components/ui/button" const stepIndicatorVariants = cva("flex items-center justify-center gap-2", { variants: { variant: { dots: "", pills: "", }, }, defaultVariants: { variant: "dots", }, }) const stepDotVariants = cva("rounded-full transition-all duration-200", { variants: { variant: { dots: "data-[state=active]:bg-foreground data-[state=completed]:bg-foreground/60 data-[state=inactive]:bg-muted-foreground/30 size-2 data-[state=active]:size-2.5", pills: "data-[state=active]:bg-foreground data-[state=completed]:bg-foreground/60 data-[state=inactive]:bg-muted-foreground/30 h-1 max-w-8 flex-1 rounded-full", }, }, defaultVariants: { variant: "dots", }, }) export interface StepIndicatorProps extends React.ComponentPropsWithoutRef<"div">, VariantProps, VariantProps { /** Current step index (1-based) */ currentStep: number /** Total number of steps */ totalSteps: number /** Optional className for each step dot */ dotClassName?: string } /** * Headless step indicator primitive. * Renders a list of step dots with proper ARIA for progress indication. * No visual styling—consumer provides via className. */ export function StepIndicator({ currentStep, totalSteps, variant = "dots", className, dotClassName, ...props }: StepIndicatorProps) { return (
{Array.from({ length: totalSteps }, (_, i) => { const stepNumber = i + 1 const isActive = currentStep === stepNumber const isCompleted = currentStep > stepNumber let stepState: "active" | "completed" | "inactive" = "inactive" if (isActive) { stepState = "active" } else if (isCompleted) { stepState = "completed" } return (
) })}
) } // ============================================================================ // Types // ============================================================================ export interface OnboardingContextValue { /** Current step index (1-based) */ currentStep: number /** Total number of steps */ totalSteps: number /** Sub-step value (e.g. feature carousel index within step 1) */ stepValue: number /** Set current step */ setStep: (step: number | ((prev: number) => number)) => void /** Set step value (sub-step) */ setStepValue: (value: number | ((prev: number) => number)) => void /** Max step value for current step (e.g. feature count - 1) */ maxStepValue: number /** Whether user can proceed to next */ canGoNext: boolean /** Whether user can go back */ canGoBack: boolean /** Navigate to previous step */ handleBack: () => void /** Navigate to next step or advance sub-step */ handleNext: () => void /** Complete onboarding */ handleComplete: () => void /** Callback when onboarding is completed */ onComplete?: () => void } // ============================================================================ // Context // ============================================================================ const OnboardingContext = createContext(null) function useOnboarding() { const ctx = useContext(OnboardingContext) if (!ctx) { throw new Error("Onboarding components must be used within Onboarding.Root") } return ctx } // ============================================================================ // Root // ============================================================================ export interface OnboardingRootProps extends PropsWithChildren, Omit, "children"> { /** Controlled step index (1-based) */ value?: number /** Default step index (uncontrolled) */ defaultValue?: number /** Callback when step changes */ onValueChange?: (step: number) => void /** Controlled sub-step value */ stepValue?: number /** Default sub-step value (uncontrolled) */ defaultStepValue?: number /** Callback when sub-step value changes */ onStepValueChange?: (value: number) => void /** Total number of steps */ totalSteps: number /** Max sub-step value for step 1 (e.g. feature count - 1). Default 0 = no sub-steps */ maxStepValue?: number /** Callback when onboarding is completed */ onComplete?: () => void /** Custom logic for whether user can proceed. Receives (step, stepValue). Default: true */ canGoNext?: (step: number, stepValue: number) => boolean } function OnboardingRoot({ value: controlledValue, defaultValue = 1, onValueChange, stepValue: controlledStepValue, defaultStepValue = 0, onStepValueChange, totalSteps, maxStepValue: controlledMaxStepValue = 0, onComplete, canGoNext: canGoNextFn, children, className, ...props }: OnboardingRootProps) { const [currentStep, setCurrentStep] = useControllableState({ prop: controlledValue, defaultProp: defaultValue, onChange: onValueChange, }) const [stepValue, setStepValueState] = useControllableState({ prop: controlledStepValue, defaultProp: defaultStepValue, onChange: onStepValueChange, }) const maxStepValue = controlledMaxStepValue ?? 0 const canGoNext = canGoNextFn ? canGoNextFn(currentStep, stepValue) : true const canGoBack = currentStep > 1 || stepValue > 0 const handleNext = useCallback(() => { if (currentStep === 1 && stepValue < maxStepValue) { setStepValueState((prev) => prev + 1) } else if (currentStep < totalSteps) { setStepValueState(0) setCurrentStep((prev) => prev + 1) } }, [ currentStep, stepValue, maxStepValue, totalSteps, setStepValueState, setCurrentStep, ]) const handleBack = useCallback(() => { if (currentStep === 1 && stepValue > 0) { setStepValueState((prev) => prev - 1) } else if (currentStep === 2) { setCurrentStep(1) setStepValueState(maxStepValue) } else if (currentStep > 1) { setCurrentStep((prev) => prev - 1) } }, [currentStep, stepValue, maxStepValue, setStepValueState, setCurrentStep]) const handleComplete = useCallback(() => { onComplete?.() }, [onComplete]) const contextValue = useMemo( () => ({ currentStep, totalSteps, stepValue, setStep: setCurrentStep, setStepValue: setStepValueState, maxStepValue, canGoNext, canGoBack, handleBack, handleNext, handleComplete, onComplete, }), [ currentStep, totalSteps, stepValue, setCurrentStep, setStepValueState, maxStepValue, canGoNext, canGoBack, handleBack, handleNext, handleComplete, onComplete, ] ) return (
{children}
) } // ============================================================================ // Step // ============================================================================ export interface OnboardingStepProps extends React.ComponentPropsWithoutRef<"div"> { /** Step index (1-based) - content renders when currentStep matches */ step: number } function OnboardingStep({ step, children, className, ...props }: OnboardingStepProps) { const { currentStep } = useOnboarding() const isActive = currentStep === step if (!isActive) { return null } return (
{children}
) } // ============================================================================ // StepIndicator // ============================================================================ export interface OnboardingStepIndicatorProps extends Omit< React.ComponentProps, "currentStep" | "totalSteps" > {} function OnboardingStepIndicator(props: OnboardingStepIndicatorProps) { const { currentStep, totalSteps } = useOnboarding() return ( ) } // ============================================================================ // Header // ============================================================================ export interface OnboardingHeaderProps extends React.ComponentPropsWithoutRef<"div"> { /** Step title (optional when using children) */ title?: string /** Step description */ description?: string /** Custom header content (overrides title/description) */ children?: React.ReactNode } function OnboardingHeader({ title, description, children, className, ...props }: OnboardingHeaderProps) { if (children) { return (
{children}
) } return (
{title != null &&

{title}

} {description &&

{description}

}
) } // ============================================================================ // Navigation // ============================================================================ export interface OnboardingNavigationProps extends React.ComponentPropsWithoutRef<"fieldset"> { /** Back button label */ backLabel?: string /** Next button label */ nextLabel?: string /** Complete button label */ completeLabel?: string /** Override can go next (when not using Root's canGoNext) */ canGoNext?: boolean /** Custom navigation content (use with asChild for full control) */ children?: React.ReactNode } function OnboardingNavigation({ backLabel = "Back", nextLabel = "Next", completeLabel = "Start Creating", canGoNext: canGoNextOverride, children, className, ...props }: OnboardingNavigationProps) { const { currentStep, totalSteps, canGoNext: contextCanGoNext, canGoBack, handleBack, handleNext, handleComplete, } = useOnboarding() const canGoNext = canGoNextOverride ?? contextCanGoNext const isLastStep = currentStep === totalSteps if (children) { return (
{children}
) } return (
{isLastStep ? ( ) : ( )}
) } // ============================================================================ // Types // ============================================================================ type Orientation = "horizontal" | "vertical" | "grid" interface ChoiceGroupContextValue { value: string | null setValue: (value: string) => void name: string orientation: Orientation } // ============================================================================ // Context // ============================================================================ const ChoiceGroupContext = createContext(null) function useChoiceGroup() { const ctx = useContext(ChoiceGroupContext) if (!ctx) { throw new Error("ChoiceGroup.Item must be used within ChoiceGroup") } return ctx } // ============================================================================ // Root // ============================================================================ export interface ChoiceGroupProps extends Omit, "defaultValue"> { /** Controlled selected value */ value?: string | null /** Default selected value (uncontrolled) */ defaultValue?: string | null /** Callback when selection changes */ onValueChange?: (value: string) => void /** Name for radio group semantics (required for accessibility) */ name: string /** Layout orientation */ orientation?: Orientation } function ChoiceGroupRoot({ value: controlledValue, defaultValue = null, onValueChange, name, orientation = "grid", children, className, ...props }: ChoiceGroupProps) { const [value, setValueState] = useControllableState({ prop: controlledValue ?? undefined, defaultProp: defaultValue ?? null, onChange: (v) => v !== null && onValueChange?.(v), }) const setValue = useCallback( (v: string) => { setValueState(v) }, [setValueState] ) const contextValue = useMemo( () => ({ value, setValue, name, orientation, }), [value, setValue, name, orientation] ) return (
{children}
) } // ============================================================================ // Item // ============================================================================ export interface ChoiceGroupItemProps extends React.ComponentPropsWithoutRef<"label"> { /** Value when this item is selected */ value: string } function ChoiceGroupItemComponent({ value: itemValue, children, className, ...props }: ChoiceGroupItemProps) { const { value, setValue, name } = useChoiceGroup() const isSelected = value === itemValue const handleChange = useCallback( (e: React.ChangeEvent) => { if (e.currentTarget.checked) { setValue(itemValue) } }, [itemValue, setValue] ) return ( ) } ChoiceGroupItemComponent.displayName = "ChoiceGroupItem" // ============================================================================ // Export // ============================================================================ export const ChoiceGroup = Object.assign(ChoiceGroupRoot, { Item: ChoiceGroupItemComponent, }) // ============================================================================ // Types // ============================================================================ interface FeatureCarouselContextValue { value: number setValue: (value: number | ((prev: number) => number)) => void totalItems: number isActive: (index: number) => boolean } // ============================================================================ // Context // ============================================================================ const FeatureCarouselContext = createContext(null) function useFeatureCarousel() { const ctx = useContext(FeatureCarouselContext) if (!ctx) { throw new Error("FeatureCarousel.Item must be used within FeatureCarousel") } return ctx } // ============================================================================ // Root // ============================================================================ export interface FeatureCarouselProps extends React.ComponentPropsWithoutRef<"div"> { /** Controlled active index */ value?: number /** Default active index (uncontrolled) */ defaultValue?: number /** Callback when active index changes */ onValueChange?: (index: number) => void /** Total number of items (derived from children if not provided) */ totalItems?: number } function FeatureCarouselRoot({ value: controlledValue, defaultValue = 0, onValueChange, totalItems: totalItemsProp, children, className, ...props }: FeatureCarouselProps) { const [value, setValue] = useControllableState({ prop: controlledValue, defaultProp: defaultValue, onChange: onValueChange, }) const totalItems = totalItemsProp ?? Children.count(children) const isActive = useCallback((index: number) => value === index, [value]) const contextValue = useMemo( () => ({ value, setValue, totalItems, isActive, }), [value, setValue, totalItems, isActive] ) return (
{children}
) } // ============================================================================ // Item // ============================================================================ export interface FeatureCarouselItemProps extends React.ComponentPropsWithoutRef<"button"> { /** Index of this item (0-based) */ index: number } function FeatureCarouselItemComponent({ index, children, className, onClick, ...props }: FeatureCarouselItemProps) { const { setValue, isActive, totalItems } = useFeatureCarousel() const active = isActive(index) const handleClick = useCallback( (e: React.MouseEvent) => { setValue(index) onClick?.(e) }, [index, setValue, onClick] ) const handleKeyDown = useCallback( (e: React.KeyboardEvent) => { if (totalItems <= 1) { return } if (e.key === "ArrowRight" || e.key === "ArrowDown") { e.preventDefault() setValue((prev) => Math.min(prev + 1, totalItems - 1)) } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") { e.preventDefault() setValue((prev) => Math.max(prev - 1, 0)) } }, [totalItems, setValue] ) return ( ) } FeatureCarouselItemComponent.displayName = "FeatureCarouselItem" // ============================================================================ // Export // ============================================================================ export const FeatureCarousel = Object.assign(FeatureCarouselRoot, { Item: FeatureCarouselItemComponent, }) // ============================================================================ // TipsList // ============================================================================ export interface TipsListProps extends React.ComponentPropsWithoutRef<"div"> { /** Optional title/label for the list */ title?: string } /** * Headless tips list primitive. * Renders an ordered list with optional title. * No visual styling—consumer provides via className. */ function TipsListRoot({ title, children, className, ...props }: TipsListProps) { const titleId = useId() return (
{title && (

{title}

)}
    {children}
) } // ============================================================================ // Item // ============================================================================ export interface TipsListItemProps extends React.ComponentPropsWithoutRef<"li"> { /** Optional number to display (for custom styling) */ number?: number } function TipsListItemComponent({ number, children, className, ...props }: TipsListItemProps) { return (
  • {number != null && ( {number} )} {children}
    • ) } // ============================================================================ // Export // ============================================================================ export const TipsList = Object.assign(TipsListRoot, { Item: TipsListItemComponent, }) // ============================================================================ // Export // ============================================================================ export const Onboarding = Object.assign(OnboardingRoot, { Step: OnboardingStep, StepIndicator: OnboardingStepIndicator, Header: OnboardingHeader, Navigation: OnboardingNavigation, }) export { useOnboarding } ``` **Update the import paths to match your project setup.** ## Usage ```tsx import { Onboarding, FeatureCarousel, ChoiceGroup, TipsList, useOnboarding, } from "@/components/ui/onboarding"; ``` ```tsx console.log("done")}> setRole(v)}> Designer Developer Be specific with your prompts. ``` ## Components ### Onboarding (Root) The root component manages step state and provides context to all children. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `totalSteps` | `number` | — | Total number of steps (required) | | `value` | `number` | — | Controlled current step (1-based) | | `defaultValue` | `number` | `1` | Default step for uncontrolled usage | | `onValueChange` | `(step: number) => void` | — | Callback when step changes | | `maxStepValue` | `number` | `0` | Max sub-step index for step 1 (e.g. feature carousel) | | `canGoNext` | `(step, stepValue) => boolean` | `() => true` | Custom gate for proceeding | | `onComplete` | `() => void` | — | Called when the last step is completed | ### Onboarding.Step Renders children only when its `step` matches the current step. | Prop | Type | Description | | ------ | -------- | -------------------- | | `step` | `number` | Step index (1-based) | ### Onboarding.Header Renders a centered title and description with serif font styling. | Prop | Type | Description | | ------------- | ----------- | -------------------------------------------- | | `title` | `string` | Step title | | `description` | `string` | Step description | | `children` | `ReactNode` | Custom content (overrides title/description) | ### Onboarding.Navigation Default navigation with Back and Next/Complete buttons. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `backLabel` | `string` | `"Back"` | Back button label | | `nextLabel` | `string` | `"Next"` | Next button label | | `completeLabel` | `string` | `"Start Creating"` | Complete button label | | `canGoNext` | `boolean` | — | Override next gate from context | | `children` | `ReactNode` | — | Custom navigation content | ### Onboarding.StepIndicator Connects to onboarding context and renders a `StepIndicator`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `variant` | `"dots" \| "pills"` | `"dots"` | Visual style of the indicators | | `dotClassName` | `string` | — | Extra class for each step dot | ### FeatureCarousel Tablist-style feature selector that syncs with `stepValue` in the onboarding context. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `value` | `number` | — | Controlled active index | | `defaultValue` | `number` | `0` | Default active index | | `onValueChange` | `(index: number) => void` | — | Callback on change | | `totalItems` | `number` | — | Total items (derived from children if omitted) | #### FeatureCarousel.Item | Prop | Type | Description | | ------- | -------- | ---------------------------- | | `index` | `number` | Index of this item (0-based) | ### ChoiceGroup Accessible radio group for single-select choices. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `name` | `string` | — | Radio group name (required for a11y) | | `value` | `string \| null` | — | Controlled selected value | | `defaultValue` | `string \| null` | `null` | Default selected value | | `onValueChange` | `(value: string) => void` | — | Callback on selection | | `orientation` | `"horizontal" \| "vertical" \| "grid"` | `"grid"` | Layout orientation | #### ChoiceGroup.Item | Prop | Type | Description | | ------- | -------- | -------------------------------- | | `value` | `string` | Value when this item is selected | ### TipsList Ordered tips list with optional visible title. | Prop | Type | Description | | ------- | -------- | ---------------------------------------------- | | `title` | `string` | Optional label (screen-reader only by default) | #### TipsList.Item | Prop | Type | Description | | -------- | -------- | --------------------------------- | | `number` | `number` | Optional step number shown inline | ## Controlled Usage ```tsx const [step, setStep] = useState(1) s !== 2 || roleSelected} onComplete={handleComplete} > {/* steps */} ``` ## Sub-steps (Feature Carousel) Pair `maxStepValue` on the root with a `FeatureCarousel` synced via `stepValue` to let users page through features before advancing: ```tsx const FEATURES = ["Generate", "Ideas", "Upload"] {({ stepValue, setStepValue }) => ( {FEATURES.map((f, i) => ( {f} ))} )} ```