# Onboarding Wizard (`onboarding-wizard`) - SignalOS widget

> Multi-step wizard shell: header, step indicator, scrollable body, and sticky footer actions.

- **Version:** 0.2.6
- **Kind:** widget · **Category:** layout
- **Install:** `npx shadcn@latest add @signalos/onboarding-wizard`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/button
- **npm dependencies:** lucide-react@^1.7.0
- **Files installed:** `src/components/widgets/onboarding-wizard/OnboardingWizard.tsx`, `src/components/widgets/onboarding-wizard/OnboardingWizard.types.ts`, `src/components/widgets/onboarding-wizard/OnboardingWizard.constants.ts`, `src/components/widgets/onboarding-wizard/OnboardingWizard.utils.ts`, `src/components/widgets/onboarding-wizard/components/Header.tsx`, `src/components/widgets/onboarding-wizard/components/StepIndicator.tsx`, `src/components/widgets/onboarding-wizard/components/FooterActions.tsx`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import OnboardingWizard from "@/components/widgets/onboarding-wizard/OnboardingWizard"
```

## Example

```tsx
import { useState } from "react"

import { OnboardingWizard } from "@/components/widgets/onboarding-wizard/OnboardingWizard"

import { OnboardingWizardStep } from "./OnboardingWizard.types"

const STEPS: OnboardingWizardStep[] = [
  { id: 1, label: "Configure Model", optional: true },
  { id: 2, label: "Data Connectors" },
  { id: 3, label: "Create Pipeline" },
]

export default function Example() {
  const [step, setStep] = useState(1)

  return (
    <OnboardingWizard
      steps={STEPS}
      currentStep={step}
      eyebrow={`Step ${step} of ${STEPS.length}`}
      title="Welcome to SignalOS"
      canGoBack={step > 1}
      canProceed
      onNext={() => setStep((s) => Math.min(s + 1, STEPS.length))}
      onBack={() => setStep((s) => Math.max(s - 1, 1))}
      onFinish={() => console.info("finished")}
    >
      <div>Step {step} content</div>
    </OnboardingWizard>
  )
}
```

## Props

### `OnboardingWizardStep`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | `number` | yes | - |  |
| `label` | `string` | yes | - |  |
| `description` | `string \| undefined` | no | - |  |
| `optional` | `boolean \| undefined` | no | - |  |

### `OnboardingWizardProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `steps` | `OnboardingWizardStep[]` | yes | - |  |
| `currentStep` | `number` | yes | - |  |
| `completedBefore` | `number \| undefined` | no | - |  |
| `eyebrow` | `ReactNode` | no | - |  |
| `title` | `ReactNode` | yes | - |  |
| `subtitle` | `ReactNode` | no | - |  |
| `children` | `ReactNode` | yes | - |  |
| `error` | `ReactNode` | no | - |  |
| `canGoBack` | `boolean \| undefined` | no | - |  |
| `canProceed` | `boolean \| undefined` | no | - |  |
| `isSubmitting` | `boolean \| undefined` | no | - |  |
| `isOptional` | `boolean \| undefined` | no | - |  |
| `onBack` | `(() => void) \| undefined` | no | - |  |
| `onNext` | `(() => void) \| undefined` | no | - |  |
| `onFinish` | `(() => void) \| undefined` | no | - |  |
| `className` | `string \| undefined` | no | - |  |
| `data-testid` | `string \| undefined` | no | - | Test identifier rendered as `data-testid` on the root element. |
| `open` | `boolean \| undefined` | no | - |  |

### `OnboardingWizardHeaderProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `eyebrow` | `ReactNode` | no | - |  |
| `title` | `ReactNode` | yes | - |  |
| `subtitle` | `ReactNode` | no | - |  |

### `OnboardingWizardStepIndicatorProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `steps` | `OnboardingWizardStep[]` | yes | - |  |
| `currentStep` | `number` | yes | - |  |
| `completedBefore` | `number \| undefined` | no | - |  |

### `OnboardingWizardFooterProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `totalSteps` | `number` | yes | - |  |
| `currentStep` | `number` | yes | - |  |
| `canGoBack` | `boolean \| undefined` | no | - |  |
| `canProceed` | `boolean \| undefined` | no | - |  |
| `isSubmitting` | `boolean \| undefined` | no | - |  |
| `isOptional` | `boolean \| undefined` | no | - |  |
| `onBack` | `(() => void) \| undefined` | no | - |  |
| `onNext` | `(() => void) \| undefined` | no | - |  |
| `onFinish` | `(() => void) \| undefined` | no | - |  |

## Changelog

## 0.2.6

- Fix cross-item imports to use canonical @/components paths; add missing signalos.category to manifests.

# onboarding-wizard
## 0.2.5
- format the code
## 0.2.4

## 0.2.1

- Fixed a malformed `sm:px-` class (missing size suffix, so it generated no
  rule) on the header wrapper - it now reads `sm:px-8`, matching `main` and
  `footer` in the same component. Previously the header lost its intended
  extra horizontal padding at `sm` and up, misaligning it against the body
  and footer.

## 0.2.0

- **Breaking:** rename the `testId` prop to `data-testid` to match the rest
  of the registry and the DOM attribute name.

## 0.1.2

- Use semantic status tokens (text-text-error, bg-bg-warning, border-border-*, bg-status-*) instead of raw palette scales so client theme overrides restyle status colors.


## 0.1.1

- Content sync fix to bring source in line with published registry payload.


## 0.1.0

- Initial release: generic multi-step wizard shell (header + step indicator +
  scrollable body + sticky footer actions) with error banner slot and
  optional-step affordance.