# Primitives

> Props of every Stepper component.

Source: https://stepperize.com/docs/v9/react/api/primitives

All primitives accept the props of the element they render, a `ref`, and
`render` to [use your own element](https://stepperize.com/docs/v9/react/guides/primitives#rendering-your-own-element).
See [Styling](https://stepperize.com/docs/v9/react/guides/styling) for their data attributes.

## Root [#root]

Renders a `div`. Creates the flow and provides it.

| Prop | Type | Description |
| --- | --- | --- |
| Every [option](https://stepperize.com/docs/v9/react/api/options) | | `linear`, `next`, `guard`, `snapshot`, `step`, `onChange`, `onFinish`, `onInvalidStep`. |
| `orientation` | `"horizontal" \| "vertical"` | Default `"horizontal"`. |
| `children` | `ReactNode \| (stepper) => ReactNode` | The function form re-renders on every change. |

`onChange` is the flow's callback, not the DOM event.

The element has `role="group"` and the name "Stepper"; pass `aria-label` or
`aria-labelledby` to describe your flow. While an async check or `onFinish` runs it has
`aria-busy` and `data-pending`; once the flow has finished it has
`data-finished`.

## List [#list]

Renders an `ol`.

| Prop | Type | Description |
| --- | --- | --- |
| `children` | `ReactNode \| (step, index) => ReactNode` | The function is called once per step; items inside it need no `step` prop. |
| `orientation` | `"horizontal" \| "vertical"` | Defaults to the root's. |

## Item [#item]

Renders an `li`.

| Prop | Type | Description |
| --- | --- | --- |
| `step` | Step id | Required outside a `List` function. |

## Trigger [#trigger]

Renders a `button` that calls `goTo` for its step. Must be inside an `Item`,
and should be inside a `List`.

It is disabled when `linear` does not allow reaching the step. In a flow that
is not linear it is a `tab`; in a linear flow it is a plain button, with
`aria-current="step"` on the current one.

## Title and Description [#title-and-description]

Render a `span` with the step's `title` or `description` field. Children
replace it.

## Indicator [#indicator]

Renders a `span` with `aria-hidden`. Empty by default: style it, or pass
children.

## Content [#content]

Renders a `div` while its step is current. It is the `tabpanel` of its trigger
in a flow rendered as tabs, and otherwise a `group` named after the step's
`title`.

| Prop | Type | Description |
| --- | --- | --- |
| `step` | Step id | Required. |
| `forceMount` | `boolean` | Keep it mounted and `hidden` while its step is not current. |

## Prev and Next [#prev-and-next]

Render a `button`.

- `Next` calls `next()` with no argument, which validates the data stored for
  the current step. On the last step it finishes the flow; it is never
  disabled for being at the end.
- `Prev` calls `prev()`, and is disabled when there is nowhere to go back to.

While an async check or `onFinish` runs, both are `aria-disabled` and ignore
clicks, and have `data-pending`.

Once the flow has finished, `Next` is `aria-disabled` with `data-disabled` and
ignores clicks, so the flow is not submitted twice. It becomes available again
when the flow changes. `Root` has `data-finished` meanwhile.

Call `event.preventDefault()` in `onClick` to handle the move yourself, for
example to pass form values:

```tsx
<Stepper.Next
  onClick={(event) => {
    event.preventDefault();
    stepper.next(form.getValues());
  }}
>
  Continue
</Stepper.Next>
```

## useItem [#useitem]

`Stepper.useItem()` returns the enclosing item.

| Field | Type | Description |
| --- | --- | --- |
| `step` | `Step` | The step, with all its fields. |
| `index` | `number` | Its position. |
| `state` | `"pending" \| "current" \| "complete"` | |
| `invalid` | `boolean` | Its last validation failed and its data has not changed since. |
| `disabled` | `boolean` | `goTo` would be refused right now. |
| `pending` | `boolean` | A move is running. Every step is `disabled` meanwhile. |

Outside an `Item` it throws [SZ101](https://stepperize.com/docs/v9/core/errors#sz101).
