Skip to content

Onboarding Modal

Multi-step onboarding dialog: a colored visual panel (giant step number by default) next to title, description, segmented progress bar and Back/Next buttons; resets on open.

brutalist/ui/onboarding-modal
Open ↗

Source

"use client";

import { useState, type ReactNode } from "react";
import { Dialog } from "radix-ui";
import { X } from "lucide-react";
import { cn } from "@/lib/utils";

export interface OnboardingStep {
  title: string;
  description: string;
  /** Visual block for the step (illustration, mini-UI…). */
  visual?: ReactNode;
}

export interface OnboardingModalProps {
  trigger?: ReactNode;
  defaultOpen?: boolean;
  steps?: OnboardingStep[];
  finishLabel?: string;
  onFinish?: () => void;
  da?: string;
}

const TONES = ["bg-da-primary text-da-primary-fg", "bg-da-accent text-da-accent-fg", "bg-da-secondary text-da-secondary-fg", "bg-da-success text-da-success-fg"];

const DEFAULT_STEPS: OnboardingStep[] = [
  { title: "Welcome aboard", description: "Shipyard turns merged pull requests into release notes. Let's get your first changelog live in three steps." },
  { title: "Connect a repo", description: "Install the GitHub app on one repository. We only read PR titles, labels and descriptions." },
  { title: "Label your PRs", description: "Use feature, fix, improvement or breaking. Anything unlabelled stays out of the changelog." },
  { title: "Publish", description: "Review the AI draft and hit publish. Your page, widget and digests update at once." },
];

export function OnboardingModal({ trigger, defaultOpen, steps = DEFAULT_STEPS, finishLabel = "Let's ship", onFinish, da = "brutalist" }: OnboardingModalProps) {
  const [step, setStep] = useState(0);
  const [open, setOpen] = useState(defaultOpen ?? false);
  const current = steps[step] ?? steps[0];
  const last = step === steps.length - 1;
  if (!current) return null;

  return (
    <Dialog.Root
      open={open}
      onOpenChange={(o) => {
        setOpen(o);
        if (o) setStep(0);
      }}
    >
      {trigger && <Dialog.Trigger asChild>{trigger}</Dialog.Trigger>}
      <Dialog.Portal>
        <Dialog.Overlay data-da={da} className="fixed inset-0 z-50 bg-da-overlay" />
        <Dialog.Content
          data-da={da}
          className="da-stroke fixed top-1/2 left-1/2 z-50 grid w-[calc(100%-2rem)] max-w-3xl -translate-x-1/2 -translate-y-1/2 bg-da-surface text-da-surface-fg shadow-da-lg outline-none md:grid-cols-2"
        >
          <div aria-hidden className={cn("da-stroke-b md:da-stroke-r relative grid min-h-48 place-items-center p-8 md:border-b-0", TONES[step % TONES.length])}>
            {current.visual ?? <span className="font-da-display text-[9rem] leading-none tracking-da-display">{step + 1}</span>}
          </div>
          <div className="flex flex-col p-6 sm:p-8">
            <div className="flex items-center justify-between">
              <p className="font-da-mono text-xs font-bold tracking-da-label uppercase" aria-live="polite">
                Step {step + 1} of {steps.length}
              </p>
              <Dialog.Close aria-label="Skip onboarding" className="da-focus grid size-8 place-items-center hover:bg-da-muted">
                <X aria-hidden className="size-5" />
              </Dialog.Close>
            </div>
            <Dialog.Title className="mt-6 font-da-display text-3xl leading-none tracking-da-display uppercase">{current.title}</Dialog.Title>
            <Dialog.Description className="mt-4 text-lg text-da-muted-fg">{current.description}</Dialog.Description>
            <div className="mt-8 flex gap-1.5" aria-hidden>
              {steps.map((s, i) => (
                <span key={s.title} className={cn("da-stroke h-3 flex-1", i <= step ? "bg-da-fg" : "bg-da-surface")} />
              ))}
            </div>
            <div className="mt-auto flex gap-3 pt-8">
              <button
                type="button"
                onClick={() => setStep((s) => s - 1)}
                disabled={step === 0}
                className="da-focus da-stroke bg-da-surface px-5 py-3 font-bold disabled:opacity-40"
              >
                Back
              </button>
              <button
                type="button"
                onClick={() => {
                  if (last) {
                    onFinish?.();
                    setOpen(false);
                  } else setStep((s) => s + 1);
                }}
                className="da-focus da-stroke flex-1 bg-da-fg px-5 py-3 font-bold text-da-bg shadow-da-sm hover:translate-x-[3px] hover:translate-y-[3px] hover:shadow-none"
              >
                {last ? finishLabel : "Next →"}
              </button>
            </div>
          </div>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

export default OnboardingModal;

modules/brutalist/ui/onboarding-modal/index.tsx

Props

PropTypeDefaultDescription
triggerReactNode—Element that opens the modal.
defaultOpenbooleanfalseOpen on mount (first-run).
stepsOnboardingStep[]—{ title, description, visual? }[].
finishLabelstring"Let's ship"Label of the last button.
onFinish() => void—Called on the last step.
dastring"brutalist"DA scope for the portal.

Other modal variants in Brutalist

Modal in other art directions

Bottom Sheet

Mobile-style bottom sheet (Radix Dialog): heavily frosted panel sliding up with a grab handle, title and description; becomes a floating centered card on wider screens.

GlassModal

Dropdown Menu

Frosted dropdown menu (Radix DropdownMenu) built from an items array: labels, icons, shortcuts, separators, checkbox items, nested submenus and a danger item.

GlassModal

Modal

Frosted glass sheet dialog (Radix): 40px backdrop blur, optional icon bubble, rise-and-pop entrance with overshoot, blurred overlay, round close button and footer actions.

GlassModal

Share Dialog

Glass share dialog: invite-by-email field with role select, people-with-access list, a general access switch (invited only / anyone with link) and a copy-link button with confirmation.

GlassModal

Command Palette

⌘K command palette (Radix Dialog): search input, results filtered as you type and grouped (actions, incidents, schedules), icons and shortcuts, arrow-key highlight, Enter to run, footer hints.

MinimalModal

Modal

Radix-based dialog with fade + subtle scale entrance, optional icon, title/description, scrollable body and a tinted footer action bar. Re-applies the DA scope inside the portal.

MinimalModal

Popover Card

Anchored popover (Radix Popover) with arrow, optional title + close button and any content — quick forms (snooze), definitions or details. Collision-aware placement.

MinimalModal

Sheet

Side sheet (Radix Dialog) sliding in from the right or left over a dimmed overlay: title and description header with close button, scrollable body and footer actions.

MinimalModal

Command Dialog

Command palette (Radix Dialog + listbox): a square panel near the top with a large borderless search, grouped results under mono headings, arrow-key navigation with an inverted active row and shortcut hints.

Mono CleanModal

Drawer

Right side panel (Radix Dialog) sliding in over a dimmed page: mono top bar with label and “Close”, large title, scrollable body with ruled rows and a sticky footer.

Mono CleanModal

Lightbox

Full-screen image viewer (Radix Dialog) on ink (stays dark in dark mode): the image frame centered, mono “03 / 04” counter and caption, Prev/Next text buttons and arrow-key navigation, thumbnails strip.

Mono CleanModal

Modal

Square dialog (Radix): a mono label + text “Close” in the top bar, a full-ink rule, a large title, body and right-aligned actions; opens with a quick fade and 8px rise.

Mono CleanModal

Confirm Dialog

Destructive confirmation (Radix AlertDialog): red warning icon, title, consequence text, optional “type VOID to confirm” guard, cancel + red confirm.

Neo CorporateModal

Modal

Corporate dialog (Radix): white card with header (title, description, close), divided scrollable body and a tinted footer bar for actions; quick fade + slight scale.

Neo CorporateModal

Payment Modal

Pay-invoice dialog: amount summary, card/bank method radio cards, method-specific fields, secure note and a pay button that switches to a success state.

Neo CorporateModal

Side Sheet

Detail drawer (Radix Dialog) sliding in from the right: full-height bordered panel with sticky header, scrollable body and footer actions — for record details.

Neo CorporateModal

Bottom Sheet

Bottom sheet (Radix Dialog): slides up from the bottom with a grab handle and very rounded top corners; becomes a centered card from sm up.

Organic SoftModal

Confirm Dialog

Gentle confirmation (Radix AlertDialog): a wilting-leaf illustration in a clay circle, serif question, kind consequence text, a sage “keep” action and a quiet clay confirm.

Organic SoftModal

Modal

Soft dialog (Radix): large-radius cream card that rises gently with a slight overshoot, serif title, round close button and pill actions.

Organic SoftModal

Welcome Modal

Onboarding dialog: an illustrated tinted header (sprout growing with each step), serif title and copy, leaf-shaped step dots, Back/Next pills and “Let’s begin” on the last step.

Organic SoftModal

Celebrate Modal

“Week complete!” celebration dialog: pastel confetti shapes burst from the center, trophy emoji, friendly copy, three pastel stat tiles and one pill button.

Soft FlatModal

Confirm Sheet

Destructive confirmation shown as a bottom sheet on mobile and a centered card on desktop: big emoji in a red-tint circle, gentle copy, red confirm with pending state and a soft cancel.

Soft FlatModal

Modal

Soft modal (Radix Dialog): big rounded white card popping in with a small bounce, pastel emoji circle, round close button, body and pill footer actions.

Soft FlatModal

Popover Menu

Rounded dropdown menu (Radix DropdownMenu) with emoji items, keyboard hints, soft highlight, separators and a red danger item; pops in with a bounce.

Soft FlatModal