Skip to Content

Onboarding Section

Present accessible, application-controlled onboarding steps, progress, and actions.

OnboardingSection presents step state supplied by your application. It does not own business logic, persistence, or completion rules.

390 × 844

Variants

Every layout uses the same caller-owned step list and completion values.

steps - Present a straightforward sequence.

390 × 844

checklist - Show completion state beside each task.

390 × 844

progress - Emphasize overall completion.

390 × 844

wizard - Focus the current step and its content.

390 × 844

cards - Give each step a distinct surface.

390 × 844

split - Pair the step list with current-step details.

390 × 844

welcome - Introduce first-run setup.

390 × 844

centered - Center a short guided flow.

390 × 844

horizontal - Scroll through a compact horizontal step rail.

390 × 844

vertical - Keep longer step descriptions in a vertical list.

390 × 844

compact - Use a denser setup checklist.

390 × 844

Interactive onboarding

The example controls its selected step and completion state in the consuming React component. Use the arrow keys, Home, and End to move through enabled steps; disabled steps are skipped and focus follows keyboard selection.

390 × 844

Accessibility

  • The section is labelled by its heading; the progress indicator exposes a progressbar name and value.
  • Completion and progress are announced through a polite status message.
  • Provide stable step IDs. Disabled steps use native disabled buttons when step selection is enabled.
  • Steps remain application-controlled; update currentStep in onStepChange and move focus only through the provided keyboard navigation.

API

PropTypeRequiredDefaultDescription
titleReactNodeYes—Section heading.
stepsreadonly OnboardingStep[]Yes—Caller-provided step records with unique IDs.
currentStepstringNoFirst incomplete enabled stepSelected step ID.
onStepChange(id: string) => voidNo—Enables keyboard-operable step selection and reports changes.
variantOnboardingSectionVariantNostepsLayout variant.
description, actions, childrenReactNodeNo—Supporting content, actions, and custom current-step content.
classNamestringNo—Additional root class.

OnboardingStep contains required id and title, plus optional description, completed, disabled, media, and action.

Customization

Use the component's className and documented slots to adapt the composition. Prefer a caller-provided ReactNode for media, actions, or controls rather than adding domain behavior to the section.

import type { ComponentProps } from "react";
import { OnboardingSection } from "@puzzle-ui/pieces";

type OnboardingSectionProps = ComponentProps<typeof OnboardingSection>;

export function CustomizedSection(props: OnboardingSectionProps) {
  return (
    <OnboardingSection
      {...props}
      className={[props.className, "brand-section"].filter(Boolean).join(" ")}
    />
  );
}

Responsive behavior

Use the preview device selector to review mobile, tablet, and desktop widths. The built-in variant controls section structure; ensure application-provided media, form controls, and children can shrink or wrap without horizontal overflow. Use the existing responsive breakpoints in scoped CSS when the consuming layout needs a product-specific adjustment.

Theme support

The section consumes semantic variables from @puzzle-ui/theme and inherits active or scoped themes. Wrap the application with Theme, and use semantic roles such as text, surface, border, and primary for local overrides. Avoid hard-coded colors, spacing, radii, and shadows.

.brand-section {
  color: var(--puzzle-color-text);
  background: var(--puzzle-color-surface);
  border-color: var(--puzzle-color-border);
}

Composition

Compose this section with the UI primitives named in its API and use the documented slots for consumer-owned controls or media. Keep data fetching, routing, validation, permissions, and persistence in the application. The children slot is intended for additional content that belongs with this section, not as a substitute for its typed data model.

TypeScript example

The package exports this component from its root. Derive a wrapper's exact prop type from the public component rather than widening it:

import type { ComponentProps } from "react";
import { OnboardingSection } from "@puzzle-ui/pieces";

type OnboardingSectionProps = ComponentProps<typeof OnboardingSection>;

export function SectionWrapper(props: OnboardingSectionProps) {
  return <OnboardingSection {...props} />;
}

Framework compatibility

The section is router-independent. Static compositions can be server-rendered; place callback-driven interactions in the framework's client boundary. See Next.js and TanStack Start integration for runnable framework examples and SSR guidance.