First-Run Experience

A multi-slide welcome dialog for new users with feature highlights and quick start guide.

Preview

Features

4-slide wizard: Welcome, Features, Quick Start, Get Started
Interactive feature cards with links or onClick handlers
Quick start checklist with navigation links
Dot indicator for slide progress
Customizable title, description, and content
Callback on completion for persistence (e.g., localStorage)
Default content included for quick setup

Install Summary

This kit will add the following files and dependencies to your project. Download the bundle and extract it into your project root.

Component Files

File	Path
first-run.tsx	components/onboarding/first-run/first-run.tsx
first-run-context.tsx	components/onboarding/first-run/first-run-context.tsx
slide-welcome.tsx	components/onboarding/first-run/slide-welcome.tsx
slide-features.tsx	components/onboarding/first-run/slide-features.tsx
slide-quickstart.tsx	components/onboarding/first-run/slide-quickstart.tsx
slide-getstarted.tsx	components/onboarding/first-run/slide-getstarted.tsx
slide-indicator.tsx	components/onboarding/first-run/slide-indicator.tsx
types.ts	components/onboarding/first-run/types.ts
index.ts	components/onboarding/first-run/index.ts

Utility Files

File	Path
design-tokens.ts	lib/design-tokens.ts

Dependencies

Install these dependencies before using the component:

Terminal

bash

npx shadcn@latest add button dialog

Terminal

bash

npm install @phosphor-icons/react

Installation

Download the complete bundle as a ZIP file, or copy the text bundle to your clipboard:

Component Files

The component consists of the following files:

1. first-run.tsx

first-run.tsx

tsx

"use client";

import { ChartLineUp as BarChart3, UsersThree as Users, PlugsConnected as Plug } from "@phosphor-icons/react";
import {
  Dialog,

2. first-run-context.tsx

first-run-context.tsx

tsx

"use client";

import {
  createContext,
  useCallback,

3. slide-welcome.tsx

slide-welcome.tsx

tsx

"use client";

import { RocketLaunch as Rocket } from "@phosphor-icons/react";
import { Button } from "@/components/ui/button";
import { useFirstRun } from "./first-run-context";

4. slide-features.tsx

slide-features.tsx

tsx

"use client";

import { CaretRight as ChevronRight } from "@phosphor-icons/react";
import { Button } from "@/components/ui/button";
import { Card, CardContent } from "@/components/ui/card";

5. slide-quickstart.tsx

slide-quickstart.tsx

tsx

"use client";

import { CaretRight as ChevronRight } from "@phosphor-icons/react";
import { Button } from "@/components/ui/button";
import { useFirstRun } from "./first-run-context";

6. slide-getstarted.tsx

slide-getstarted.tsx

tsx

"use client";

import { Confetti as PartyPopper } from "@phosphor-icons/react";
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";

7. slide-indicator.tsx

slide-indicator.tsx

tsx

"use client";

import { cn } from "@/lib/utils";
import { useFirstRun } from "./first-run-context";

8. types.ts

types.ts

tsx

import type { ReactNode } from "react";

export type FirstRunSlide = "welcome" | "features" | "quickstart" | "getstarted";

export interface Feature {

9. index.ts

index.ts

tsx

export { FirstRun } from "./first-run";
export { FirstRunProvider, useFirstRun } from "./first-run-context";
export type {
  Feature,
  FirstRunProps,
  FirstRunSlide,
  QuickStartItem,
} from "./types";

Shared Utilities

This component uses shared utility functions. These are included in the bundle above:

design-tokens.ts

tsx

// Border radius
export const radius = {
  card: "rounded-xl",
  badge: "rounded-full",
  button: "rounded-lg",

Usage

app/layout.tsx

tsx

import { useState } from "react";
import { FirstRun } from "@/components/onboarding/first-run";
import type { Feature, QuickStartItem } from "@/components/onboarding/first-run";
import { BarChart3, Users, Plug } from "@phosphor-icons/react";

Props

Prop	Type	Default
open	boolean	required
onOpenChange	(open: boolean) => void	required
onComplete	() => void	-
features	Feature[]	-
quickStartItems	QuickStartItem[]	-
title	string	-
description	string	-