# First Use

> A setup checklist for someone's first visit: steps with their actions, progress dots with a count, and a dismiss button.

- Name: `first-use`
- Status: beta
- Categories: onboarding, checklist, setup, getting started, progress
- Files: the install writes `first-use.tsx`, and any part files named `first-use-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- npm packages: `lucide-react`. The install adds them.
- Other registry items: `@txbrendan/card`, `@txbrendan/button`, `@txbrendan/skeleton`, `@txbrendan/step-dots`. The install adds them.
- Gallery: https://txbrendan.dev/blocks/first-use
- Registry item: https://txbrendan.dev/r/first-use.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@txbrendan": "https://txbrendan.dev/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @txbrendan/theme
   ```

3. Add the block. It also adds every component it uses:

   ```bash
   npx shadcn@latest add @txbrendan/first-use
   ```

## Use it for

- The top of a new account's home page: three to six steps that get someone to a working setup.
- Mark a step done from real data, like a project that exists, not from a click on its button.
- Give each step one action that takes people straight to it. The checklist shows it until the step is done.
- Save the dismissal in onDismiss, so the card stays hidden on the next visit.
- Set loading while you find out which steps are done, so the card does not flash the wrong ones.

## Avoid it for

- A tour of the interface. Put help where people need it, next to the thing it explains.
- A list or page with nothing in it yet. Use Empty State.
- Steps people must finish before they can use the app. Put those in the sign-up flow.
- More than six steps. Cut it down, or split it into stages.

## Props

- `steps`: `{ id: string; title: ReactNode; description?: ReactNode; done?: boolean; action?: ReactNode }[]`. The checklist, in order. Each id must be unique. The first step that is not done is the current step. Steps can be done in any order. The dots fill in one per done step, from the left, so they show how many are done, not which. Past eight steps, only the count shows.
- `title`: `ReactNode`. Default `"Set up your workspace"`. The card's heading.
- `description`: `ReactNode`. One line under the title: what finishing the steps gets people.
- `headingLevel`: `1 | 2 | 3 | 4 | 5 | 6`. Default `2`. The title's heading level, so it fits under the heading above it.
- `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. Color of the done marks, the current step's ring, and the progress dots.
- `loading`: `boolean`. Default `false`. Shows placeholder steps while you find out which are done.
- `loadingText`: `string`. Default `"Loading setup steps"`. What the status line tells screen readers while loading.
- `dismissible`: `boolean`. Default `true`. Shows the dismiss button.
- `dismissLabel`: `string`. Default `"Dismiss"`. The dismiss button's name for screen readers.
- `onDismiss`: `() => void`. Called when people dismiss the card, after it hides. Save this, so it stays hidden next time.
- `completeTitle`: `ReactNode`. Default `"You're all set"`. Shown in place of the steps once every step is done, or when there are no steps.
- `completeDescription`: `ReactNode`. Default `"You finished every step."`. One line under completeTitle.
- `className`: `string`. Extra classes on the outer section, which holds the container query.

## Accessibility

- The card is a section named by its title, which is a real heading, an h2 by default. Set headingLevel to fit your page.
- The steps are an ordered list. The current step has aria-current="step", and every step's text ends with (done) or (not done) for screen readers.
- The check marks and rings are hidden from screen readers, since the text already says each step's state.
- A status line says "2 of 4 done", and loadingText while loading. It stays on the page, so screen readers hear each new count.
- The dots and the count beside them are hidden from screen readers, since the status line says the same count. The dots are not buttons, so nothing focusable is hidden.
- Forced colors mode drops fills. There the dots hide and the count shows alone, done marks keep their circle as a border, and loading shows loadingText as words.
- The dismiss button is named by dismissLabel and described by the title. Dismissing removes the card, so focus falls back to the page. If that matters, move focus in onDismiss.

## Examples

### A new workspace

```tsx
<FirstUse
  title="Set up your workspace"
  description="Four steps, about five minutes."
  steps={[
    { id: "profile", title: "Add your name and photo", done: true },
    { id: "team", title: "Invite your team", done: true },
    {
      id: "calendar",
      title: "Connect your calendar",
      description: "Meetings show up next to your tasks.",
      action: <Button size="sm">Connect</Button>,
    },
    {
      id: "project",
      title: "Create your first project",
      action: <Button size="sm" emphasis="outline">New project</Button>,
    },
  ]}
  onDismiss={() => saveSetting("setupGuideHidden", true)}
/>
```

### While you check which steps are done

```tsx
<FirstUse steps={steps ?? []} loading={steps === undefined} />
```

### Keep it until the steps are done

```tsx
<FirstUse steps={steps} dismissible={false} tone="brand" />
```