---
title: "Onboarding"
description: "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](/docs/components/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.

_Live example of Onboarding — see the page for the rendered demo._

## Installation

```bash
npx newtui@latest add onboarding
``` Registry dependencies, installed with it: stepper, button.

Files written — React: components/onboarding.tsx. Vue: components/onboarding/Onboarding.vue, components/onboarding/types.ts, components/onboarding/index.ts.

## Usage

React:

```tsx
import { Onboarding } from "@/components/onboarding"
```

Vue:

```ts
import { Onboarding } from "@/components/onboarding"
```

## API reference

**`Onboarding`**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `steps` | `{ title: string; description?: string }[]` | — | The stages, in order. The current step's title is the heading above its content. |
| `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. |
| `onStepChange` | `(step: number) => void` | — | React only. Called when the step changes; Vue emits `update:step`. |
| `onComplete / @complete` | `() => void` | — | Called when the last step's button is pressed. |
| `canContinue` | `boolean` | `true` | Whether the current step may be left. |
| `labels` | `{ back: string; next: string; finish: string }` | — | The wording of the buttons. |
| `children / default slot` | `(step: number) => React.ReactNode / scoped slot` | — | The content of the step whose index it is given. |

Keep 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. Override a token rather than editing the component.
