{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "onboarding", "type": "registry:ui", "description": "Composable multi-step onboarding primitives: Onboarding root with step navigation, FeatureCarousel, ChoiceGroup radio selector, TipsList, and StepIndicator with dots and pills variants", "dependencies": [ "@radix-ui/react-use-controllable-state", "class-variance-authority" ], "registryDependencies": [ "button" ], "files": [ { "path": "registry/default/ui/onboarding.tsx", "content": "\"use client\"\n\nimport type * as React from \"react\"\nimport {\n Children,\n createContext,\n useCallback,\n useContext,\n useId,\n useMemo,\n type PropsWithChildren,\n} from \"react\"\nimport { useControllableState } from \"@radix-ui/react-use-controllable-state\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport { Button } from \"@/components/ui/button\"\n\nconst stepIndicatorVariants = cva(\"flex items-center justify-center gap-2\", {\n variants: {\n variant: {\n dots: \"\",\n pills: \"\",\n },\n },\n defaultVariants: {\n variant: \"dots\",\n },\n})\n\nconst stepDotVariants = cva(\"rounded-full transition-all duration-200\", {\n variants: {\n variant: {\n 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\",\n pills:\n \"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\",\n },\n },\n defaultVariants: {\n variant: \"dots\",\n },\n})\n\nexport interface StepIndicatorProps\n extends React.ComponentPropsWithoutRef<\"div\">,\n VariantProps,\n VariantProps {\n /** Current step index (1-based) */\n currentStep: number\n /** Total number of steps */\n totalSteps: number\n /** Optional className for each step dot */\n dotClassName?: string\n}\n\n/**\n * Headless step indicator primitive.\n * Renders a list of step dots with proper ARIA for progress indication.\n * No visual styling—consumer provides via className.\n */\nexport function StepIndicator({\n currentStep,\n totalSteps,\n variant = \"dots\",\n className,\n dotClassName,\n ...props\n}: StepIndicatorProps) {\n return (\n \n {Array.from({ length: totalSteps }, (_, i) => {\n const stepNumber = i + 1\n const isActive = currentStep === stepNumber\n const isCompleted = currentStep > stepNumber\n let stepState: \"active\" | \"completed\" | \"inactive\" = \"inactive\"\n if (isActive) {\n stepState = \"active\"\n } else if (isCompleted) {\n stepState = \"completed\"\n }\n return (\n \n )\n })}\n \n )\n}\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport interface OnboardingContextValue {\n /** Current step index (1-based) */\n currentStep: number\n /** Total number of steps */\n totalSteps: number\n /** Sub-step value (e.g. feature carousel index within step 1) */\n stepValue: number\n /** Set current step */\n setStep: (step: number | ((prev: number) => number)) => void\n /** Set step value (sub-step) */\n setStepValue: (value: number | ((prev: number) => number)) => void\n /** Max step value for current step (e.g. feature count - 1) */\n maxStepValue: number\n /** Whether user can proceed to next */\n canGoNext: boolean\n /** Whether user can go back */\n canGoBack: boolean\n /** Navigate to previous step */\n handleBack: () => void\n /** Navigate to next step or advance sub-step */\n handleNext: () => void\n /** Complete onboarding */\n handleComplete: () => void\n /** Callback when onboarding is completed */\n onComplete?: () => void\n}\n\n// ============================================================================\n// Context\n// ============================================================================\n\nconst OnboardingContext = createContext(null)\n\nfunction useOnboarding() {\n const ctx = useContext(OnboardingContext)\n if (!ctx) {\n throw new Error(\"Onboarding components must be used within Onboarding.Root\")\n }\n return ctx\n}\n\n// ============================================================================\n// Root\n// ============================================================================\n\nexport interface OnboardingRootProps\n extends PropsWithChildren,\n Omit, \"children\"> {\n /** Controlled step index (1-based) */\n value?: number\n /** Default step index (uncontrolled) */\n defaultValue?: number\n /** Callback when step changes */\n onValueChange?: (step: number) => void\n /** Controlled sub-step value */\n stepValue?: number\n /** Default sub-step value (uncontrolled) */\n defaultStepValue?: number\n /** Callback when sub-step value changes */\n onStepValueChange?: (value: number) => void\n /** Total number of steps */\n totalSteps: number\n /** Max sub-step value for step 1 (e.g. feature count - 1). Default 0 = no sub-steps */\n maxStepValue?: number\n /** Callback when onboarding is completed */\n onComplete?: () => void\n /** Custom logic for whether user can proceed. Receives (step, stepValue). Default: true */\n canGoNext?: (step: number, stepValue: number) => boolean\n}\n\nfunction OnboardingRoot({\n value: controlledValue,\n defaultValue = 1,\n onValueChange,\n stepValue: controlledStepValue,\n defaultStepValue = 0,\n onStepValueChange,\n totalSteps,\n maxStepValue: controlledMaxStepValue = 0,\n onComplete,\n canGoNext: canGoNextFn,\n children,\n className,\n ...props\n}: OnboardingRootProps) {\n const [currentStep, setCurrentStep] = useControllableState({\n prop: controlledValue,\n defaultProp: defaultValue,\n onChange: onValueChange,\n })\n\n const [stepValue, setStepValueState] = useControllableState({\n prop: controlledStepValue,\n defaultProp: defaultStepValue,\n onChange: onStepValueChange,\n })\n\n const maxStepValue = controlledMaxStepValue ?? 0\n\n const canGoNext = canGoNextFn ? canGoNextFn(currentStep, stepValue) : true\n\n const canGoBack = currentStep > 1 || stepValue > 0\n\n const handleNext = useCallback(() => {\n if (currentStep === 1 && stepValue < maxStepValue) {\n setStepValueState((prev) => prev + 1)\n } else if (currentStep < totalSteps) {\n setStepValueState(0)\n setCurrentStep((prev) => prev + 1)\n }\n }, [\n currentStep,\n stepValue,\n maxStepValue,\n totalSteps,\n setStepValueState,\n setCurrentStep,\n ])\n\n const handleBack = useCallback(() => {\n if (currentStep === 1 && stepValue > 0) {\n setStepValueState((prev) => prev - 1)\n } else if (currentStep === 2) {\n setCurrentStep(1)\n setStepValueState(maxStepValue)\n } else if (currentStep > 1) {\n setCurrentStep((prev) => prev - 1)\n }\n }, [currentStep, stepValue, maxStepValue, setStepValueState, setCurrentStep])\n\n const handleComplete = useCallback(() => {\n onComplete?.()\n }, [onComplete])\n\n const contextValue = useMemo(\n () => ({\n currentStep,\n totalSteps,\n stepValue,\n setStep: setCurrentStep,\n setStepValue: setStepValueState,\n maxStepValue,\n canGoNext,\n canGoBack,\n handleBack,\n handleNext,\n handleComplete,\n onComplete,\n }),\n [\n currentStep,\n totalSteps,\n stepValue,\n setCurrentStep,\n setStepValueState,\n maxStepValue,\n canGoNext,\n canGoBack,\n handleBack,\n handleNext,\n handleComplete,\n onComplete,\n ]\n )\n\n return (\n \n \n {children}\n \n \n )\n}\n\n// ============================================================================\n// Step\n// ============================================================================\n\nexport interface OnboardingStepProps\n extends React.ComponentPropsWithoutRef<\"div\"> {\n /** Step index (1-based) - content renders when currentStep matches */\n step: number\n}\n\nfunction OnboardingStep({\n step,\n children,\n className,\n ...props\n}: OnboardingStepProps) {\n const { currentStep } = useOnboarding()\n const isActive = currentStep === step\n\n if (!isActive) {\n return null\n }\n\n return (\n \n {children}\n \n )\n}\n\n// ============================================================================\n// StepIndicator\n// ============================================================================\n\nexport interface OnboardingStepIndicatorProps\n extends Omit<\n React.ComponentProps,\n \"currentStep\" | \"totalSteps\"\n > {}\n\nfunction OnboardingStepIndicator(props: OnboardingStepIndicatorProps) {\n const { currentStep, totalSteps } = useOnboarding()\n return (\n \n )\n}\n\n// ============================================================================\n// Header\n// ============================================================================\n\nexport interface OnboardingHeaderProps\n extends React.ComponentPropsWithoutRef<\"div\"> {\n /** Step title (optional when using children) */\n title?: string\n /** Step description */\n description?: string\n /** Custom header content (overrides title/description) */\n children?: React.ReactNode\n}\n\nfunction OnboardingHeader({\n title,\n description,\n children,\n className,\n ...props\n}: OnboardingHeaderProps) {\n if (children) {\n return (\n \n {children}\n \n )\n }\n\n return (\n \n {title != null &&

{title}

}\n {description &&

{description}

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

\n {title}\n

\n )}\n \n {children}\n \n
\n )\n}\n\n// ============================================================================\n// Item\n// ============================================================================\n\nexport interface TipsListItemProps\n extends React.ComponentPropsWithoutRef<\"li\"> {\n /** Optional number to display (for custom styling) */\n number?: number\n}\n\nfunction TipsListItemComponent({\n number,\n children,\n className,\n ...props\n}: TipsListItemProps) {\n return (\n \n {number != null && (\n \n {number}\n \n )}\n {children}\n \n )\n}\n\n// ============================================================================\n// Export\n// ============================================================================\n\nexport const TipsList = Object.assign(TipsListRoot, {\n Item: TipsListItemComponent,\n})\n\n// ============================================================================\n// Export\n// ============================================================================\n\nexport const Onboarding = Object.assign(OnboardingRoot, {\n Step: OnboardingStep,\n StepIndicator: OnboardingStepIndicator,\n Header: OnboardingHeader,\n Navigation: OnboardingNavigation,\n})\n\nexport { useOnboarding }\n", "type": "registry:ui" } ] }