For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt, and this page is available as Markdown at https://rickyshin93.github.io/tao-ui/components/form.md.
v0.0.57
  • English
  • Form

    Data Entry@rockshin/tao-ui

    Collects and validates field values with an antd-aligned API (rules, dependencies, Form.List) on top of the rc-form engine.

    When to use

    Use Form with Form.Item when fields need a value store, rule validation, or submit handling. Use the lighter FormField when you manage state yourself.

    Direct Form.Item children have 4px bottom spacing when a feedback row is present (--tao-size-unit), or 20px otherwise (--tao-padding-md). --tao-form-field-item-gap overrides either default. Stack and FormSection manage spacing for items placed inside them. noStyle adds neither a shell nor spacing, and standalone FormField layout is unchanged.

    At the default 12–14px message sizes, the reserved line is 18px high; with its 2px top margin and 4px trailing gap, feedback occupies 24px. Larger custom message text can increase the line height.

    Form.Item reserves one feedback line when it has validation rules or an explicit help, extra or validateStatus. Single-line validation messages can appear or disappear without moving subsequent fields or buttons. Longer messages wrap and expand the space naturally to avoid overlapping content. Fields without validation or feedback do not reserve an empty row. Use help="" to keep the row when controlling messages manually.

    Recommended

    • Declare validation as rules on Form.Item; the required mark is inferred from rules.
    • Use dependencies for cross-field rules such as password confirmation.
    • Use Form.useForm() for imperative control (setFieldsValue, resetFields, submit).
    • Values written through setFields — including the controlled fields prop — clear stale validation errors for fields whose value changed; include errors/warnings in the same entry to provide fresh validation state.
    • Set size or disabled on Form to cascade them to every control inside.

    Avoid

    • Do not bind the same name in two mounted Form.Items.
    • Do not mix manual value/onChange props with a bound Form.Item on the same control.

    Examples

    Basic usage

    TSX

    Validation

    TSX

    Horizontal layout

    TSX

    Complete form

    Combine fields, sections, and actions into an end-to-end entry and submission flow.

    Personal Information

    Basic details about you.

    ✉️
    +86

    Optional. Used for recovery.

    Preferences

    Configure your workspace.

    TSX

    Cross-field validation

    Validate against another field and update feedback when the related value changes.

    TSX

    Dynamic field lists

    Add and remove repeated fields with Form.List, keeping form values and field indexes aligned.

    TSX

    Scroll to a claim field

    Get the instance with Form.useForm(), a Form ref, or Form.useFormInstance(). Array paths and full Form.List paths such as ['claims', 0, 'email'] are supported.

    Scroll down, or use the button to reveal the field.

    TSX

    Defaults to scrollMode: 'if-needed' and block: 'nearest'. Accepts behavior, block, inline, boundary, scrollMode and other scroll options; focus: true focuses the control after starting the scroll. Only mounted fields can be located; reveal conditional or unmounted tab content first. Custom controls must forward ref (a DOM node or an instance with nativeElement) or id.

    <Form
      form={form}
      onFinishFailed={({ errorFields }) => {
        if (errorFields.length) {
          form.scrollToField(errorFields[0].name, { focus: true });
        }
      }}
    />

    API

    Form

    PropertyDescriptionTypeDefault Value
    layoutLabel/control arrangement inherited by Form.Item. Defaults to 'vertical'."vertical" | "horizontal" | undefined-
    sizeCascades a control size to everything inside the form.TaoSize | undefined-
    disabledDisables every tao-ui control inside the form (e.g. while submitting).boolean | undefined-