Onboarding Carousel React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Onboarding Carousel is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import OnboardingCarousel from @/components/ui/onboarding-carousel.

"use client"

import { useRouter } from "next/navigation"
import { OnboardingCarousel, type OnboardingSlide } from "@/components/ui/onboarding-carousel"

const slides: OnboardingSlide[] = [
  {
    id: "clients",
    title: "Every client in one place",
    description: "Companies, contacts and balances, the same on your phone and at the office.",
    image: "/onboarding/clients.svg",
    background: "var(--info-soft)",
  },
  {
    id: "invoices",
    title: "Invoices in 30 seconds",
    description: "Issue the invoice from your phone and we email it to your client.",
    image: "/onboarding/invoices.svg",
    background: "var(--success-soft)",
  },
  {
    id: "offline",
    title: "Works offline too",
    description: "Everything syncs when you are back online.",
    image: "/onboarding/offline.svg",
  },
]

export default function Welcome() {
  const router = useRouter()
  return (
    <OnboardingCarousel
      layout="screen"
      slides={slides}
      persistKey="onboarding-v1"
      showBack
      labels={{ skip: "Skip", next: "Continue", back: "Back", done: "Get started", region: "Welcome" }}
      onComplete={() => router.replace("/home")}
    />
  )
}

Props

• slides*
  OnboardingSlide[]

  { id, title, description?, media?, image?, imageAlt?, background?, foreground? }. media is any node (a composed ui vignette, an svg); image is contained in the media area, or full-bleed behind the text with a bottom scrim when foreground is "light". background is any CSS color or token (var(--info-soft)) and cross-fades while swiping; without one the root's surface shows.

• layoutdefault "fill"
  "fill" | "screen" | "card"

  fill takes the parent's height (a route of its own inside an app shell). screen is min-h-dvh with safe-area padding at the top and bottom. card is a 420 x 640px rounded surface, capped at 85dvh.

• modaldefault false
  boolean

  Renders it in a Radix dialog with a focus trap and a hidden title: a full screen below 768px that slides up, a centered card from 768px. Closing (Escape, the overlay) counts as Skip. layout is ignored.

• defaultOpendefault false
  boolean

  Modal mode: open on mount. The playground turns modal on with it.

• open
  boolean

  Modal mode, controlled. Pair with onOpenChange.

• onOpenChange
  (open: boolean) => void

  Modal mode: the trigger opened it, or Skip, Escape, the overlay or the last button closed it.

• trigger
  ReactNode

  Modal mode: the element that opens it, rendered asChild (a Button).

• indicatordefault "dots"
  "dots" | "bars" | "progress" | "counter"

  The carousel's indicators: dots whose active one stretches, story bars, one progress bar, or a 2 / 4 counter. Hidden with a single slide.

• indicatorPositiondefault "bottom"
  "top" | "bottom"

  bottom sits above Next (beside the circle). top puts it in the header next to Skip, the stories look.

• nextVariantdefault "button"
  "button" | "circle"

  button: a full-width Next that becomes Get started. circle: a round arrow ringed by the progress that grows into the Get started pill on the last slide.

• sizedefault "md"
  "sm" | "md" | "lg"

  Title 24 / 28 / 32px, description 15 / 16 / 17px, indicators, and the Next button (40 / 48 / 48px, 44px on touch at sm; the circle 48 / 56 / 64px).

• aligndefault "center"
  "center" | "start"

  Text alignment of the title and description.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  The Next / Get started button, the circle's ring and the active dot or bar.

• colordefault ""
  string

  Any CSS color. Replaces the tone; text on the button turns black or white by lightness.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  Corner shape of the Next and Back buttons in the button variant (the circle is always round).

• showSkipdefault true
  boolean

  The Skip button in the header. It fades out on the last slide.

• showBackdefault false
  boolean

  A back chevron before Next from the second slide.

• skipTodefault "last"
  "last" | "complete"

  Skip jumps to the last slide, or finishes right away (fade out, then onSkip and onComplete).

• parallaxdefault true
  boolean

  While swiping, the media moves at 0.6x the slide and the text at 0.9x. Off under reduced motion.

• hapticsdefault true
  boolean

  A "selection" tick through lib/haptics when a finger or pen swipe lands on a new slide. Never on a mouse drag, taps, keys or mount; silent on desktops.

• persistKeydefault ""
  string

  When set, a finish or a skip that ends the tour (skipTo="complete", closing the modal) is remembered in localStorage (use-persisted-state) and nothing renders afterwards; a modal stays closed unless its trigger opens it. The server renders the slides; a remembered finish fades them out after hydration (a modal never flashes). Clear it with writePersisted(key, null).

• index
  number

  The current slide, controlled. A jump scrolls there (instantly under reduced motion); values past the end clamp.

• defaultIndexdefault 0
  number

  The first slide shown, uncontrolled. The tour also returns here after it finishes.

• onIndexChange
  (index: number) => void

  Every settled change: a swipe, Next, Back, Skip, a dot or a key.

• onComplete
  () => void

  The last slide's button (and Skip with skipTo="complete"), after the fade out.

• onSkip
  (index: number) => void

  Skip was pressed (or the modal was closed) on this slide.

• labels
  Partial<OnboardingCarouselLabels>

  skip "Skip", next "Next", back "Back", done "Get started", region "Welcome" (the region label and the modal title fallback), slide(i, n) "Slide 2 of 4", goTo(i) "Go to slide 3". Pass only the keys you translate.

• setApi
  (api: CarouselApi) => void

  The embla api, for custom controls.

• classNames
  Partial<Record<"header" | "skip" | "slide" | "media" | "title" | "description" | "footer" | "indicator" | "back" | "next", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root, merged last. Override the tone vars here, e.g. [--tone:#0f766e].

Parts

FAQ

Used in

More React mobile components