# Snake stepper
> Five-step onboarding progress drawn as a pixel snake that circles the current step, slithers to the next, eats it and grows.
- Element: `<px-stepper>`
- React: `import { PxStepper } from "@/components/lumesec/px-stepper"`
- Collection: Pixel Lab (https://elements.lumesec.ai/components/pixel-lab)
- Registry item: https://elements.lumesec.ai/r/px-stepper.json
- Page: https://elements.lumesec.ai/components/pixel-lab/stepper



Live preview: https://elements.lumesec.ai/view/px-stepper

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-stepper.js"></script>

<px-stepper></px-stepper>
```

## Installation

```bash
npx shadcn@latest add @lumesec/px-stepper
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-stepper.json
```

## Usage

React:

```tsx
import { PxStepper } from "@/components/lumesec/px-stepper";

export function Example() {
  return (
    <PxStepper />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-stepper.js"></script>

<px-stepper></px-stepper>
```

## Behaviour

Onboarding progress as a pixel snake. It idles in a loop around the current step, slithers along the path to the next one, eats it and grows.

## API reference

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event      | React prop   | Detail             | Description                                                |
| ---------- | ------------ | ------------------ | ---------------------------------------------------------- |
| `change`   | `onChange`   | `{ step: number }` | Fires when the snake arrives at a step. `step` is 1-based. |
| `complete` | `onComplete` | `{}`               | Fires when Finish is pressed on the last step.             |

### Methods

Call them on the element, for example through a React ref.

| Method                   | Description                                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `go(direction: 1 \| -1)` | Moves to the next or previous step; on the last step, `go(1)` completes onboarding. Ignored while the snake is moving. |

## Accessibility

* The canvas has `role="img"` with an `aria-label` such as "Onboarding progress, step 2 of 5, Workspace".
* The step title is an `aria-live="polite"` region; the subtitle is plain text.
* Back and Next are native buttons. Back is disabled on the first step and while the snake moves; Next reads Finish on the last step.
* Reduced motion: the snake jumps straight to the next step instead of slithering and sparks are skipped; it still circles the current step.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--foreground`, `--lumesec` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-fg` and `--ui-muted`.

## Notes

* The steps are built-in demo content: Account, Workspace, Connect, Invite and Launch, each with a fixed subtitle.
* The canvas is 104px tall and animates continuously while on screen. On narrow layouts the step names shrink (down to 7px) so neighbours do not overlap.