Skip to the content

Form

Form renders a form from a fields map: each key becomes a Field with its own Zod validation, wired through React Hook Form. handleSubmit runs only after every field validates.
Forms

When to use

Use when
  • A form has several fields and validation matters.
  • The fields can be described as data (static, from a back-end or a feature flag).
  • Fields appear or disappear based on other values.
Avoid when
  • It is a single search or filter control — use Input directly.
  • The layout of label and control is bespoke — compose Field or the controls yourself.

Usage

<Form
  handleSubmit={(values) => console.log(values)}
  fields={{
    name: {
      label: 'Name',
      component: Input,
      validation: z.string().min(1, 'Required'),
      inputProps: { placeholder: 'Type your name', clearable: true },
    },
    email: { label: 'E-mail', component: Input, validation: z.email('Not a valid email') },
  }}
/>

Without children, Form renders a submit Button labelled by submitLabel (default Enviar). Validation runs on submit; set mode (onBlur, onChange, onTouched, all) to validate earlier. A field that fails turns to the error state and shows the schema's message (hintErrorText is the fallback, default Something went wrong). A field hidden by conditionalFields is still validated on submit — make its schema .optional(). Declare a field with newField(...) to type-check its inputProps against component.

Layout

Without medias, fields stack in a column. With medias, each fields key is a grid area, plus button for the default submit button. Re-arrange the areas by the slot width with cq (an ancestor needs containment) or by the viewport with viewportMedias.

<Flex containment="inline-size">
  <Form
    handleSubmit={onSubmit}
    fields={fields}
    medias={{ columns: '1fr', areas: '"name" "email" "button"' }}
    cq={{ md: { columns: '1fr 1fr', areas: '"name email" "button button"' } }}
  />
</Flex>

Submit button

children replaces the default button. Pass a function to read the current values:

<Form fields={fields} handleSubmit={onSubmit}>
  {({ acceptedTerms }) => <Button type="submit" disabled={!acceptedTerms} text="Send" />}
</Form>

Examples

Dynamic fields

conditionalFields maps a field to a predicate over the current values. When it returns false, the field unmounts.

const [show, setShow] = useState({ phone: false });

<Flex gap="medium">
  <Checkbox checked={show.phone} onChange={() => setShow((s) => ({ phone: !s.phone }))} label="Phone" />
  <Form
    handleSubmit={onSubmit}
    conditionalFields={{ phone: () => show.phone }}
    fields={{
      name: { label: 'Name', component: Input, validation: z.string().min(1, 'Required') },
      phone: { label: 'Phone', component: InputMask, inputProps: { mask: '(00) 0 0000-0000' } },
    }}
  />
</Flex>;

Every field type

Loading...

Accessibility

  • Form renders a native <form>: with a submit button present, Enter in a text field submits it.
  • Each Field label targets its control through for/id, using the fields key as the id.
  • A failing control gets aria-invalid and aria-describedby pointing at its error text.

Properties

The forwarded ref exposes the React Hook Form API (setValue, reset, trigger, getValues, …).

See also