---
title: "StepsForm"
description: "One long form, filled in over several steps."
category: Form
status: beta
since: 0.9.2
tags: [form, steps, wizard]
syncStatus: reviewed
verified: true
---

## Usage

### Basic
Each step checks only its own fields and the last one submits; with `persist`, the draft keeps the current step too, so a reload comes back to it.
::::TuffDemoWrapper{demo="StepsFormBasicDemo" code-lang="vue"}
---
code: |
  <script setup lang="ts">
  import { reactive, ref } from 'vue'

  const active = ref(0)
  const team = reactive({ name: '', handle: '', email: '', role: 'member', plan: '' })
  const roles = [
    { value: 'admin', label: 'Admin' },
    { value: 'member', label: 'Member' },
  ]
  const rules = {
    name: { required: true, message: 'Enter a team name' },
    handle: [
      { required: true, message: 'Enter a team address' },
      { pattern: /^[a-z0-9-]+$/, message: 'Use lowercase letters, digits or hyphens' },
    ],
    email: { type: 'email', message: 'Enter a valid email address' },
    plan: { required: true, message: 'Choose a plan' },
  }

  async function create(values) {
    await createTeam(values)
  }
  </script>

  <template>
    <TxStepsForm
      id="new-team"
      v-model:active="active"
      :model="team"
      :rules="rules"
      persist
      submit-text="Create team"
      @submit="create"
    >
      <TxFormStep title="Team">
        <TxFormItem label="Team name" prop="name">
          <TuffInput v-model="team.name" />
        </TxFormItem>
        <TxFormItem label="Team address" prop="handle" help="Lowercase letters, digits or hyphens">
          <TuffInput v-model="team.handle" />
        </TxFormItem>
      </TxFormStep>
      <TxFormStep title="Invite">
        <TxFormItem label="Member email" prop="email">
          <TuffInput v-model="team.email" type="email" />
        </TxFormItem>
        <TxFormItem label="Role" prop="role">
          <TxSelect v-model="team.role" :options="roles" />
        </TxFormItem>
      </TxFormStep>
      <TxFormStep title="Plan">
        <TxFormItem label="Plan" prop="plan">
          <TxRadioGroup v-model="team.plan" type="standard" direction="row">
            <TxRadio value="free" label="Free" />
            <TxRadio value="pro" label="Pro" />
            <TxRadio value="team" label="Team" />
          </TxRadioGroup>
        </TxFormItem>
      </TxFormStep>
    </TxStepsForm>
  </template>
---
::::

### Skipping and Custom Actions
The `actions` slot replaces the buttons at the bottom; a parent that sets `active` moves straight there without any check, which can skip an optional step.

```vue
<TxStepsForm v-model:active="active" :model="team" @submit="create">
  …
  <template #actions="{ last, back, submitting }">
    <TxButton v-if="active > 0" :disabled="submitting" @click="back">Back</TxButton>
    <TxButton v-if="active === 1" variant="ghost" @click="active = 2">Invite later</TxButton>
    <TxButton variant="primary" native-type="submit" :loading="submitting">{{ last ? 'Create team' : 'Next' }}</TxButton>
  </template>
</TxStepsForm>
```

### Best Practices

- Keep each step to three to five fields, and name each step with a noun for what it asks.
- Give the form an `id` with `persist`. The draft keeps the step, so a user who reloads or comes back does not start over.
- A skipped step is still checked by the final submit: keep required fields out of optional steps.
- Steps forms do not autosave. To keep progress along the way, use a `persist` draft.
- Outside English, pass `prevText`, `nextText` and `submitText`. Built-in text such as the draft notice comes from `messages`, or from `provideTxFormHost` for every form at once.

## API Reference

### TxStepsForm

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `active` | `number` | - | The step shown, counted from 0. Use with `v-model:active`, or leave it to the form. |
| `prevText` | `string` | `'Back'` | Text of the Back button. |
| `nextText` | `string` | `'Next'` | Text of the Next button. |
| `submitText` | `string` | `'Submit'` | Text of the submit button on the last step. |

#### Inherited from TxForm

Every `TxForm` prop except `autosave` applies too.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | - | Form id; prefixes the `<form>` and every field id, and keys the draft. |
| `model` | `FormValues` | - | The form's data; a `TxFormItem`'s `prop` points at a field in it. |
| `rules` | `FormRules` | - | Validation rules, keyed by field. |
| `schema` | `FormStandardSchema` | - | A Standard Schema v1 validator, such as Zod or Valibot, checked against the whole model. |
| `layout` | `'stacked' \| 'side' \| 'auto' \| 'inline'` | `'auto'` | Label layout; `auto` uses side labels from 520px wide. |
| `labelPosition` | `'left' \| 'right' \| 'top'` | - | Older label placement: `top` is `stacked`; `left` and `right` are `side`. |
| `labelAlign` | `'start' \| 'end'` | `'end'` | Alignment inside the side label column; `start` when `labelPosition="left"`. |
| `labelWidth` | `string \| number` | - | Widest the side label column may grow; narrower when every label is. |
| `requiredMark` | `'asterisk' \| 'optional' \| 'none'` | - | How required fields are marked. |
| `validateOn` | `'blur' \| 'submit'` | - | When a field's first message appears; it re-checks on every edit after that. |
| `messages` | `Partial<FormMessages>` | - | Overrides built-in text, such as the draft notices and error prefixes. |
| `size` | `'small' \| 'medium' \| 'large'` | - | Passed to the controls inside that have sizes. |
| `disabled` | `boolean` | `false` | Disables every control inside that reads the form. |
| `readonly` | `boolean` | `false` | Shows values to read: controls can be focused and copied but not changed, and no field is marked required; submitting still works. |
| `reconcile` | `FormReconcile` | - | Decides what the model holds when incoming values meet fields the user changed. |
| `persist` | `boolean \| FormPersistOptions` | - | Saves input as a draft under `id`, restored after a reload, including the current step. |
| `leaveConfirm` | `FormLeaveConfirm \| false` | - | Whether to ask before leaving with unsaved changes; `false` never asks. |
| `onSubmit` | `(values: FormValues, event?: Event) => unknown` | - | Submit callback, called once every check passes; the same as `@submit`. |

#### Events

| Event | Payload | Description |
|-------|---------|-------------|
| `update:active` | `(step: number)` | The form moved forward, back, or to a step whose field failed. |
| `submit-success` | `(values: FormValues)` | The last step was submitted and went through. |
| `validate` | `(valid: boolean)` | As on `TxForm`. |
| `persist-error` | `(error: unknown)` | As on `TxForm`. |

#### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `default` | `{ active, dirty, valid, submitting, submitted, errors, rootError }` | The `TxFormStep`s. |
| `actions` | `{ active, last, back, submitting }` | Replaces Back and Next or Submit. Move forward with a `native-type="submit"` button, so the current step is checked. |

#### Exposed Methods

| Name | Type | Description |
|------|------|-------------|
| `form` | `TxForm` | The form inside, with every `TxForm` method. |
| `back` | `() => void` | Goes to the step before, as Back does. |

### TxFormStep

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | required | Names the step in the header, and the group its fields are in. |
| `description` | `string` | - | Text under the title in the header. |

#### Slots

| Slot | Props | Description |
|------|-------|-------------|
| `default` | - | The form items of the step. |

## Overview

- Every step stays mounted and only the current one shows, so the final submit checks every field. When a field fails, the form goes back to its step and focuses it.
- Next is the form's submit button. It checks only the current step's fields and moves on, putting focus on the next step's group: a screen reader reads the step's name, and Tab goes on to its first field.
- Moving on is not submitting: the next step's fields show messages only once the user changes and leaves them, or submits again.
- With `persist`, the draft keeps the current step, and restoring the draft goes back to it. A submit that goes through deletes the draft.
- Steps register once they have mounted: on the server and in the first render in the browser, the header is empty until they do.
- A parent that sets `active` moves straight there, without a check and without moving focus.

## Technologies

- One `TxForm` holds every step, and `TxSteps` draws the header. Each step is a `role="group"` named by its `title`.
- `TxFormStep` takes the form's columns through CSS subgrid, so in side layout the label columns of every step line up.
- Source: `packages/tuffex/packages/components/src/steps-form/`.

<TuffDocSourceLink />
