Forms

Zen provides a complete form system built on react-hook-form . The Form and FormField components handle validation, error display, and field state management with minimal boilerplate.

How it works

The form system consists of several components that work together:

• Form - Wraps your form and provides react-hook-form context
• FormField - Connects any input component to the form with automatic value binding and validation
• FormButtons - Container for form action buttons
• FormSubmitButton - Submit button with automatic loading and disabled states
• FormResetButton - Reset button that clears the form to default values

Basic usage

Wrap your inputs with FormField components inside a Form. Each FormField needs a name that corresponds to a key in your form data.

Validation

Add validation rules to FormField using the rules prop. This uses react-hook-form’s validation API.

Common validation rules

Loading states

FormSubmitButton automatically shows a loading spinner and disables itself while the form is submitting. This happens when your onSubmit handler returns a Promise.

The submit button is automatically disabled when:

• The form has not been modified (isDirty is false)
• The form has validation errors (isValid is false)
• The form is currently submitting (isSubmitting is true)

You can override this behavior with the isDisabled prop.

Error handling

Pass an error prop to Form to display an error banner above the form. This is useful for showing server-side validation errors or API failures.

All form inputs

FormField works with all Zen input components. The field automatically binds the value and onChange props.

Dynamic fields with FormFieldArray

Use FormFieldArray when you need to manage a list of fields that can be added or removed dynamically.

Accessing form state

The Form component accepts a render function as children, giving you access to the full react-hook-form API.

<Form defaultValues={{ name: '' }} onSubmit={handleSubmit}>
  {({ watch, formState }) => (
    <>
      <FormField name="name" label="Name">
        <TextField />
      </FormField>
      <Text>Current value: {watch('name')}</Text>
      <Text>Form is dirty: {formState.isDirty ? 'Yes' : 'No'}</Text>
      <FormButtons>
        <FormSubmitButton variant="primary">Submit</FormSubmitButton>
      </FormButtons>
    </>
  )}
</Form>

Schema validation

Use the resolver prop to integrate with schema validation libraries like Zod or Yup.

import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
 
const schema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
});
 
function MyForm() {
  return (
    <Form
      resolver={zodResolver(schema)}
      onSubmit={handleSubmit}
    >
      <FormField name="email" label="Email">
        <TextField />
      </FormField>
      <FormField name="password" label="Password">
        <PasswordField />
      </FormField>
      <FormButtons>
        <FormSubmitButton variant="primary">Submit</FormSubmitButton>
      </FormButtons>
    </Form>
  );
}

Controlled forms

Use the values prop instead of defaultValues when you need to control form values externally. The form will reset when the values change.

function EditUserForm({ user }) {
  return (
    <Form
      values={{ name: user.name, email: user.email }}
      onSubmit={handleSubmit}
    >
      <FormField name="name" label="Name">
        <TextField />
      </FormField>
      <FormField name="email" label="Email">
        <TextField />
      </FormField>
      <FormButtons>
        <FormSubmitButton variant="primary">Save</FormSubmitButton>
      </FormButtons>
    </Form>
  );
}

Preventing enter key submission

Use preventSubmit to stop the form from submitting when the user presses Enter. Useful for forms where you want explicit button clicks only.

<Form preventSubmit onSubmit={handleSubmit}>
  <FormField name="search" label="Search">
    <TextField />
  </FormField>
  <FormButtons>
    <FormSubmitButton variant="primary">Search</FormSubmitButton>
  </FormButtons>
</Form>

Component props

Form

FormField

FormFieldArray

FormSubmitButton

FormResetButton