SetupGuide

A floating checklist in the bottom-end lane: progress, the next task, and every task when unfolded, remembered across visits.

New

Since 0.8.0

import { SetupGuide } from "@butteryui/react";

Demo

"Get your shop ready" opens folded at the bottom end of the window, 2 of 5 tasks done.

title

defaultOpen

When to use it

Use it for

Getting a new account set up over several visits: add a coffee, set shipping, connect a bank
A handful of tasks people can do in any session, with the next one a press away

Not for

One suggestion: use Banner or RecommendationCard
Steps that must happen in one sitting: use a Dialog with Onboarding

Examples

Grouped setup

A shop's welcome card that opens its setup guide: tasks in groups that fold, progress on the card and in the guide.

Welcome to your shop

2 of 5 tasks done

Review the steps

The guide's unfolding kept in state: a button on the page shows it with every step, and its own chevron folds it.

The guide is put away.

Roastery setup

A new roastery's setup, two of three tasks done, floating at the window's bottom end once it's shown.

Variants and states

A checklist in the lane

Show it, then unfold it to see every task in groups that fold, the next one's group open and its action ready. Finish them all and it says you're all set. Dismiss it and it fades away.

The guide floats at the bottom end of the window. Mark tasks done here to watch its bar fill.

Props

SetupGuide

Prop	Type	Default	Description
`title`	`string`	`"Setup guide"`	What it's for. Defaults to `"Setup guide"`. It names the guide.
`tasks` required	`readonly SetupTask[]`		The tasks, in the order to do them. The first one not done is next.
`open`	`boolean`		Whether it's unfolded, when you control it.
`defaultOpen`	`boolean`	`false`	Whether it starts unfolded. Defaults to `false`.
`onOpenChange`	`((open: boolean) => void)`		Called when it unfolds or folds.
`storageKey`	`string`		Remembers whether it's unfolded and whether it was dismissed under this key, across visits.
`onDismiss`	`(() => void)`		Called once it has faded and gone.
`footer`	`ReactNode`		What sits under the unfolded steps, past a hairline, such as a link to talk to someone.
`labels`	`Partial<SetupGuideLabels>`		Its words, for another language or your own.

It also takes Omit<MotionElementProps<"div">, "title">.

SetupTask

One task in a setup guide.

Field	Type	Description
`id` required	`string`	Identifies the task among the others.
`title` required	`string`	What to do, such as "Add your first coffee".
`description`	`string`	A line more about it, under the title when the guide is unfolded.
`done`	`boolean`	Whether it's done. The app knows; the guide shows it.
`action`	`GuidanceAction`	Where to do it: the "Next:" link takes the task's title, and the unfolded guide shows this as a button.
`group`	`string`	The group it's listed under when the guide is unfolded, such as "Take payments". Tasks with the same group sit under one header, where the group's first task is, which folds; the group holding the next task starts open.

SetupGuideLabels

The words a `SetupGuide` shows and announces.

Field	Type	Description
`next` required	`string`	Before the next task when folded.
`expand` required	`string`	Names the button that unfolds it.
`collapse` required	`string`	Names the button that folds it.
`dismiss` required	`string`	Names the dismiss button.
`allDone` required	`string`	Takes the place of the next task once every task is done.
`done` required	`string`	Read before a done task's title.
`toDo` required	`string`	Read before a task still to do.
`progress` required	`(done: number, total: number) => string`	The progress, read with the bar, such as "2 of 5 done".
`steps` required	`string`	Names the list of steps, which takes focus while it scrolls so the keyboard can scroll it.

GuidanceAction

What a guidance part points to: a label, and where it goes or what it does.

Field	Type	Description
`label` required	`string`	What it says, such as "Connect a label printer".
`href`	`string`	Makes it a link to this page.
`onClick`	`((event: MouseEvent<HTMLElement>) => void)`	Runs when it's pressed, or as its link is followed, where a router can take over.

Accessibility

A region named by its title. The progress bar is named by the title too and reads as how many are done. The unfold button says whether it's open and points at the task list; each task is read as Done or To do before its title, and the next one's action is a button or a link. A group's header is a button that says whether the group is open and points at its tasks. The dismiss button is named Dismiss; as the guide goes, focus in it moves on to the next tab stop.

Keys	What they do
`Enter or Space`	Presses the focused button: unfolds or folds the guide, opens or closes a group, runs the next task's action or dismisses the guide
`Enter`	Follows the next task's link
`Up and Down arrows`	Scroll the steps, with their list focused, once there are more than the guide shows

Motion

It changes shape as one surface, on `spring.smooth`, or `spring.morph` for a big change, rather than closing and reopening.

With reduced motion: It fades in and out over 100ms without rising, and its unfolding, its groups and their chevrons, and the progress bar's fill all land at once.

Layout

It floats in the bottom-end lane, 288px wide but never wider than the lane, 8px from the lane's other items. Folded, it's as tall as its title, progress bar and next task; unfolded, its steps scroll inside it past 320px, each group's header is a 36px row that truncates and shows in full on hover, and its other buttons are 28px, with a 24px hit area on the next task's link.

See it in the roastery demo.

SetupGuide

Demo

When to use it

Use it for

Not for

Examples

Grouped setup

Review the steps

Roastery setup

Variants and states

A checklist in the lane

Props

SetupGuide

SetupTask

SetupGuideLabels

GuidanceAction

Accessibility

Motion

Layout

Related