StepsForm
One long form, filled in over several steps.
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.
Loading demo...
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.
<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
idwithpersist. 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
persistdraft. - Outside English, pass
prevText,nextTextandsubmitText. Built-in text such as the draft notice comes frommessages, or fromprovideTxFormHostfor 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 TxFormSteps. |
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
activemoves straight there, without a check and without moving focus.
Technologies
- One
TxFormholds every step, andTxStepsdraws the header. Each step is arole="group"named by itstitle. TxFormSteptakes 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/.
查看源码
packages/tuffex/packages/components/src/steps-form/index.ts