Onboarding
A short setup flow: a stepper, the current step's content and the buttons that move through it.
A wizard for a task with a few fixed stages, assembled from a Stepper and two buttons: creating a server, connecting a bot, a first-run setup. The block owns the order and the navigation; what each step asks is yours.
The content is a function of the step’s index in React and a scoped slot in Vue. Set canContinue to false while the current step is incomplete and the forward button waits.
"use client"
import * as React from "react"
import { Onboarding } from "@/registry/bases/newt/blocks/onboarding/onboarding"
import {
Alert,
AlertDescription,
AlertTitle,
} from "@/registry/bases/newt/ui/alert"
import {
CheckboxGroup,
CheckboxOption,
} from "@/registry/bases/newt/ui/checkbox-group"
import {
Field,
FieldHelp,
Input,
Label,
} from "@/registry/bases/newt/ui/form-fields"
import { Radio, RadioGroup } from "@/registry/bases/newt/ui/radio"
const STEPS = [
{ title: "Name your server", description: "You can change it later" },
{ title: "What is it for?", description: "Sets the defaults" },
{ title: "Starting channels", description: "Pick at least one" },
]
export default function OnboardingDemo() {
const [name, setName] = React.useState("Build Club")
const [purpose, setPurpose] = React.useState("community")
const [channels, setChannels] = React.useState<readonly string[]>(["general"])
const [step, setStep] = React.useState(0)
const [done, setDone] = React.useState(false)
const canContinue =
step === 0 ? name.trim() !== "" : step === 2 ? channels.length > 0 : true
if (done) {
return (
<Alert variant="success" className="max-w-xl">
<AlertTitle>{name} is ready</AlertTitle>
<AlertDescription>
Created with {channels.length}{" "}
{channels.length === 1 ? "channel" : "channels"}.
</AlertDescription>
</Alert>
)
}
return (
<Onboarding
className="max-w-xl"
aria-label="Create a server"
steps={STEPS}
step={step}
onStepChange={setStep}
canContinue={canContinue}
onComplete={() => setDone(true)}
>
{(current) =>
current === 0 ? (
<Field>
<Label htmlFor="onboarding-name">Server name</Label>
<Input
id="onboarding-name"
value={name}
onChange={(event) => setName(event.target.value)}
/>
<FieldHelp>
Members see this at the top of the channel list.
</FieldHelp>
</Field>
) : current === 1 ? (
<RadioGroup
label="Purpose"
value={purpose}
onValueChange={setPurpose}
>
<Radio
value="community"
description="Open to anyone with the link."
>
A community
</Radio>
<Radio
value="team"
description="Invite only, for people you work with."
>
A team
</Radio>
</RadioGroup>
) : (
<CheckboxGroup
label="Starting channels"
value={channels}
onValueChange={setChannels}
>
<CheckboxOption value="general">#general</CheckboxOption>
<CheckboxOption value="help" description="Questions and answers">
#help
</CheckboxOption>
<CheckboxOption value="release-notes">
#release-notes
</CheckboxOption>
</CheckboxGroup>
)
}
</Onboarding>
)
}<script setup lang="ts">
import { computed, ref } from "vue"
import { Onboarding } from "~~/registry/bases/newt/blocks/onboarding"
import {
Alert,
AlertDescription,
AlertTitle,
} from "~~/registry/bases/newt/ui/alert"
import {
CheckboxGroup,
CheckboxOption,
} from "~~/registry/bases/newt/ui/checkbox-group"
import {
Field,
FieldHelp,
Input,
Label,
} from "~~/registry/bases/newt/ui/form-fields"
import { Radio, RadioGroup } from "~~/registry/bases/newt/ui/radio"
const STEPS = [
{ title: "Name your server", description: "You can change it later" },
{ title: "What is it for?", description: "Sets the defaults" },
{ title: "Starting channels", description: "Pick at least one" },
]
const name = ref("Build Club")
const purpose = ref("community")
const channels = ref<readonly string[]>(["general"])
const step = ref(0)
const done = ref(false)
const canContinue = computed(() => {
if (step.value === 0) return String(name.value).trim() !== ""
if (step.value === 2) return channels.value.length > 0
return true
})
</script>
<template>
<Alert v-if="done" variant="success" class="max-w-xl">
<AlertTitle>{{ name }} is ready</AlertTitle>
<AlertDescription>
Created with {{ channels.length }}
{{ channels.length === 1 ? "channel" : "channels" }}.
</AlertDescription>
</Alert>
<Onboarding
v-else
v-model:step="step"
class="max-w-xl"
aria-label="Create a server"
:steps="STEPS"
:can-continue="canContinue"
@complete="done = true"
>
<template #default="{ step: current }">
<Field v-if="current === 0">
<Label for="onboarding-name">Server name</Label>
<Input id="onboarding-name" v-model="name" />
<FieldHelp>Members see this at the top of the channel list.</FieldHelp>
</Field>
<RadioGroup v-else-if="current === 1" v-model="purpose" label="Purpose">
<Radio value="community" description="Open to anyone with the link.">
A community
</Radio>
<Radio
value="team"
description="Invite only, for people you work with."
>
A team
</Radio>
</RadioGroup>
<CheckboxGroup v-else v-model="channels" label="Starting channels">
<CheckboxOption value="general">#general</CheckboxOption>
<CheckboxOption value="help" description="Questions and answers">
#help
</CheckboxOption>
<CheckboxOption value="release-notes">#release-notes</CheckboxOption>
</CheckboxGroup>
</template>
</Onboarding>
</template>Installation
npx newtui@latest add onboardingnpx shadcn@latest add @newtui/onboardingnpx shadcn-vue@latest add @newtui/onboardingpnpm dlx newtui@latest add onboardingpnpm dlx shadcn@latest add @newtui/onboardingpnpm dlx shadcn-vue@latest add @newtui/onboardingyarn dlx newtui@latest add onboardingyarn dlx shadcn@latest add @newtui/onboardingyarn dlx shadcn-vue@latest add @newtui/onboardingbunx newtui@latest add onboardingbunx shadcn@latest add @newtui/onboardingbunx shadcn-vue@latest add @newtui/onboardingdeno run -A npm:newtui@latest add onboardingdeno run -A npm:shadcn@latest add @newtui/onboardingdeno run -A npm:shadcn-vue@latest add @newtui/onboardingvlx newtui@latest add onboardingvlx shadcn@latest add @newtui/onboardingvlx shadcn-vue@latest add @newtui/onboardingvp dlx newtui@latest add onboardingvp dlx shadcn@latest add @newtui/onboardingvp dlx shadcn-vue@latest add @newtui/onboardingnubx newtui@latest add onboardingnubx shadcn@latest add @newtui/onboardingnubx shadcn-vue@latest add @newtui/onboardingnlx newtui@latest add onboardingnlx shadcn@latest add @newtui/onboardingnlx shadcn-vue@latest add @newtui/onboardingupx newtui@latest add onboardingupx shadcn@latest add @newtui/onboardingupx shadcn-vue@latest add @newtui/onboarding- newtui
- shadcn
- npm
- pnpm
- yarn
- bun
- deno
- vlt
- vp
- nub
- ni
- upm
The shadcn CLI needs the @newtui registry in your components.json. Set it up.
Copy the source into your project
"use client"
import * as React from "react"
import { cn } from "@/lib/utils"
import { Button } from "@/registry/bases/newt/ui/button"
import { Stepper, type StepperStep } from "@/registry/bases/newt/ui/stepper"
/** The wording of the three buttons. */
export interface OnboardingLabels {
back: string
next: string
finish: string
}
export interface OnboardingProps extends Omit<
React.ComponentProps<"section">,
"children" | "onChange"
> {
steps: readonly StepperStep[]
/** Index of the step being shown. Leave undefined to let the block own it. */
step?: number
defaultStep?: number
onStepChange?: (step: number) => void
/** Called when the last step's button is pressed. */
onComplete?: () => void
/** Whether the current step may be left. Defaults to yes. */
canContinue?: boolean
labels?: OnboardingLabels
/** The content of the step whose index it is given. */
children: (step: number) => React.ReactNode
}
const defaultLabels: OnboardingLabels = {
back: "Back",
next: "Next",
finish: "Finish",
}
/*
* A short setup flow: where you are in it, the current step's own content,
* and the two buttons that move through it. The content is a function of the
* step, so each step stays an ordinary component of yours and the block only
* owns the order. Moving to another step moves focus to its heading, so a
* screen reader starts from the new content.
*/
export function Onboarding({
steps,
step,
defaultStep = 0,
onStepChange,
onComplete,
canContinue = true,
labels = defaultLabels,
className,
children,
...props
}: OnboardingProps) {
const [internal, setInternal] = React.useState(defaultStep)
const current = Math.min(step ?? internal, steps.length - 1)
const last = current === steps.length - 1
const heading = React.useRef<HTMLHeadingElement | null>(null)
const moved = React.useRef(false)
React.useEffect(() => {
if (moved.current) heading.current?.focus()
}, [current])
const goTo = (next: number) => {
moved.current = true
if (step === undefined) setInternal(next)
onStepChange?.(next)
}
return (
<section
className={cn(
"flex w-full flex-col gap-6 rounded-[var(--newt-radius-lg)] border border-newt-border bg-newt-bg-surface p-6",
className
)}
{...props}
>
<Stepper steps={steps} value={current} />
<div className="flex flex-col gap-4">
<h2
ref={heading}
tabIndex={-1}
className="m-0 text-lg font-semibold leading-6 text-newt-text-primary focus:outline-none"
>
{steps[current]?.title}
</h2>
{children(current)}
</div>
<div className="flex justify-between gap-2">
<Button
variant="secondary"
disabled={current === 0}
onClick={() => goTo(current - 1)}
>
{labels.back}
</Button>
<Button
disabled={!canContinue}
onClick={() => {
if (last) onComplete?.()
else goTo(current + 1)
}}
>
{last ? labels.finish : labels.next}
</Button>
</div>
</section>
)
}<script setup lang="ts">
import { computed, nextTick, ref, type HTMLAttributes } from "vue"
import { Button } from "~~/registry/bases/newt/ui/button"
import { Stepper, type StepperStep } from "~~/registry/bases/newt/ui/stepper"
import { cn } from "@/lib/utils"
import type { OnboardingLabels } from "./types"
/*
* A short setup flow: where you are in it, the current step's own content,
* and the two buttons that move through it. The content is the default slot,
* which is handed the step's index, so each step stays an ordinary component
* of yours and the block only owns the order. Moving to another step moves
* focus to its heading, so a screen reader starts from the new content.
*/
const props = withDefaults(
defineProps<{
class?: HTMLAttributes["class"]
steps: readonly StepperStep[]
/** Whether the current step may be left. */
canContinue?: boolean
labels?: OnboardingLabels
}>(),
{
canContinue: true,
labels: () => ({ back: "Back", next: "Next", finish: "Finish" }),
}
)
const emit = defineEmits<{
/** Fired when the last step's button is pressed. */
(e: "complete"): void
}>()
/** Index of the step being shown. Use `v-model:step` to control it. */
const step = defineModel<number>("step", { default: 0 })
const heading = ref<HTMLHeadingElement | null>(null)
const current = computed(() => Math.min(step.value, props.steps.length - 1))
const last = computed(() => current.value === props.steps.length - 1)
async function goTo(next: number) {
step.value = next
await nextTick()
heading.value?.focus()
}
function forward() {
if (last.value) emit("complete")
else void goTo(current.value + 1)
}
</script>
<template>
<section
:class="
cn(
'flex w-full flex-col gap-6 rounded-[var(--newt-radius-lg)] border border-newt-border bg-newt-bg-surface p-6',
props.class
)
"
>
<Stepper :steps="props.steps" :value="current" />
<div class="flex flex-col gap-4">
<h2
ref="heading"
tabindex="-1"
class="m-0 text-lg font-semibold leading-6 text-newt-text-primary focus:outline-none"
>
{{ props.steps[current]?.title }}
</h2>
<slot :step="current" />
</div>
<div class="flex justify-between gap-2">
<Button
variant="secondary"
:disabled="current === 0"
@click="goTo(current - 1)"
>
{{ props.labels.back }}
</Button>
<Button :disabled="!props.canContinue" @click="forward">
{{ last ? props.labels.finish : props.labels.next }}
</Button>
</div>
</section>
</template>/** The wording of the three buttons. */
export interface OnboardingLabels {
back: string
next: string
finish: string
}export { default as Onboarding } from "./Onboarding.vue"
export type { OnboardingLabels } from "./types"Update the import paths
The files import @/lib/utils and sibling components through the aliases in your components.json. Point them at wherever those live in your project.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Onboarding to your React project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
No CLI, no components.json: paste this into Claude, Cursor, Copilot or any coding assistant and it adds Onboarding to your Vue project by hand. The prompt carries the source of every file the CLI would write — this component's and those of the components it builds on — with the imports already pointed at the default aliases.
Usage
import { Onboarding } from "@/components/onboarding"
export function Example() {
return <Onboarding />
}<script setup lang="ts">
import { Onboarding } from "@/components/onboarding"
</script>
<template>
<Onboarding />
</template>API reference
Onboarding
steps?{ title: string; description?: string }[]
The stages, in order. The current step's title is the heading above its content.
{ title: string; description?: string }[]step / v-model:step?number
Index of the step being shown. In React, leave it undefined and pass `defaultStep` to let the block own it.
numberonStepChange?(step: number) => void
React only. Called when the step changes; Vue emits `update:step`.
(step: number) => voidonComplete / @complete?() => void
Called when the last step's button is pressed.
() => voidcanContinue?boolean
Whether the current step may be left.
booleantruelabels?{ back: string; next: string; finish: string }
The wording of the buttons.
{ back: string; next: string; finish: string }children / default slot?(step: number) => React.ReactNode / scoped slot
The content of the step whose index it is given.
(step: number) => React.ReactNode / scoped slotKeep each step’s answers in your own state, as the example does, so going back shows what was entered.
Accessibility
Moving to another step moves focus to that step’s heading, so a screen reader starts from the new content instead of staying on a button whose label just changed. The stepper marks the step in progress with aria-current="step". A disabled forward button gives no reason, so say what is missing near the field that needs it. Give the block an aria-label naming the task.
Tokens
Onboarding reads its colours, radii and motion from the --newt-* tokens installed with the library. Override a token and every component that reads it follows, including this one — see the token layer.