StepsForm
steps-formSplits a validated workflow across ordered steps with controlled navigation.
Usage
Basic usage
Steps indicator + Previous/Next/Submit navigation; only the current step content is mounted, the value is retained by the consumer useForm step.
- Basic informationName
- Company InformationCompany
- Contact informationEmail
<StepsForm
onFinish={async () => { await api.save(); }}
steps={[
{ title: "Basic information", content: <Field label="Name"><Input /></Field> },
{ title: "Company Information", content: <Field label="Company"><Input /></Field> },
{ title: "Contact Information", content: <Field label="Email"><Input /></Field> },
]}
/>Step by step verification
onStepValidate Verify this step field before moving forward; return false / reject to prevent moving forward, pending during button loading.
- Upload
- Confirm
<StepsForm
onStepValidate={async (step) =>
(await form.validateField(fieldsOf(step))) == null
}
steps={steps}
/>Vertical steps
direction=vertical Makes step indicators line up vertically to fit into narrow sidebars.
- First step
- Step 2
<StepsForm direction="vertical" steps={steps} />When to use
Use StepsForm for guided flows such as registration, account setup, or data import when a long form should be divided and validated step by step. Form and ProForm show all fields and submit once; StepsForm renders only the current step. Field values remain in the consumer's useForm instance because StepsForm does not own form state.
Import
import { StepsForm } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| steps* | StepsFormStep[] | — | Step definitions containing title, description, content, nextDisabled, nextText, and showNav. |
| current | number | — | Zero-based current step in controlled mode. |
| defaultCurrent | number | 0 | Initial step when uncontrolled. |
| direction | "horizontal" | "vertical" | "horizontal" | Steps indicator direction. |
| className | string | — | Additional class name for the root element. |
Events
| Event | Type | Description |
|---|---|---|
| onCurrentChange | (current: number) => void | Called with the new zero-based index when the step changes. |
| onStepValidate | (currentStep: number) => boolean | Promise<boolean> | Runs before leaving a step. Return false or reject to block navigation; async work keeps the forward button loading. |
| onFinish | () => void | Promise<void> | Called when submitting the final step; a Promise enables submit-button loading. |
StepsFormStep fields: title: ReactNode (required), description?, content: ReactNode (required and rendered only for the current step), nextDisabled? (defaults to false and prevents advancing from this step), nextText? (overrides the localized forward-button label), and showNav? (defaults to true; set it to false to hide this step's footer navigation, typically for a result step with its own actions).
Example
const form = useForm({ initialValues: { name: "", company: "" } });
const name = form.register("name", { rules: [{ required: true, message: "Please enter name" }] });
<StepsForm
onStepValidate={async (step) => {
if (step === 0) return (await form.validateField("name")) == null;
return true;
}}
onFinish={async () => {
const r = await form.validate();
if (r.ok) await api.save(r.values);
}}
steps={[
{ title: "Basic information", content: (
<Field label="Name" error={name.error}>
<Input value={name.value as string} onChange={name.onChange} onBlur={name.onBlur} />
</Field>
) },
{ title: "Company information", content: <Field label="Company">{/* ... */}</Field> },
]}
/>Usage guidelines
- StepsForm does not own field values. Keep them in the consumer's
useFormor unmounted step content will lose local input state. InonStepValidate, validate only the current step withform.validateField; a fullform.validate()would reject empty future fields. - Pair controlled
currentwithonCurrentChange, or navigation cannot advance. - For a result step with its own actions such as “Start again,” set
showNav: falseto hide built-in navigation.
Related
Form · ModalForm / DrawerForm · ProForm · LoginForm · Field · SearchForm