Components/StepsForm

StepsForm

One long form, filled in over several steps.

VerifiedSince 0.9.2

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 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

PropTypeDefaultDescription
activenumber-The step shown, counted from 0. Use with v-model:active, or leave it to the form.
prevTextstring'Back'Text of the Back button.
nextTextstring'Next'Text of the Next button.
submitTextstring'Submit'Text of the submit button on the last step.

Inherited from TxForm

Every TxForm prop except autosave applies too.

PropTypeDefaultDescription
idstring-Form id; prefixes the <form> and every field id, and keys the draft.
modelFormValues-The form's data; a TxFormItem's prop points at a field in it.
rulesFormRules-Validation rules, keyed by field.
schemaFormStandardSchema-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".
labelWidthstring | 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.
messagesPartial<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.
disabledbooleanfalseDisables every control inside that reads the form.
readonlybooleanfalseShows values to read: controls can be focused and copied but not changed, and no field is marked required; submitting still works.
reconcileFormReconcile-Decides what the model holds when incoming values meet fields the user changed.
persistboolean | FormPersistOptions-Saves input as a draft under id, restored after a reload, including the current step.
leaveConfirmFormLeaveConfirm | 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

EventPayloadDescription
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

SlotPropsDescription
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

NameTypeDescription
formTxFormThe form inside, with every TxForm method.
back() => voidGoes to the step before, as Back does.

TxFormStep

Props

PropTypeDefaultDescription
titlestringrequiredNames the step in the header, and the group its fields are in.
descriptionstring-Text under the title in the header.

Slots

SlotPropsDescription
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/.
查看源码
packages/tuffex/packages/components/src/steps-form/index.ts