Form

Organize fields, labels and validation feedback, and collect form data.

Submission and validation

basic.tsx

import { Button, Flex, Form, FormField, Input, Select, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function FormBasic() {
  const [result, setResult] = useState('');
  return (
    <Form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        setResult(`${data.get('name')} · ${data.get('email')} · ${data.get('team')}`);
      }}
      onReset={() => setResult('')}
    >
      <FormField label="Name" required>
        <Input name="name" placeholder="Your name" />
      </FormField>
      <FormField label="Work email" required help="Used for project notifications">
        <Input name="email" type="email" placeholder="hello@example.com" />
      </FormField>
      <FormField label="Team" required>
        <Select
          name="team"
          options={[
            { value: 'design', label: 'Design team' },
            { value: 'engineering', label: 'Engineering team' },
          ]}
        />
      </FormField>
      <FormField>
        <Flex gap="md" align="center" wrap justify="center">
          <Button type="submit">Submit</Button>
          <Button type="reset" variant="outline">
            Reset
          </Button>
        </Flex>
      </FormField>
      {result && (
        <output>
          <Text tone="muted">{result}</Text>
        </output>
      )}
    </Form>
  );
}

Label widths

Automatic label widths

label-width.tsx

import { Button, Flex, Form, FormField, Input, Space, Switch } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function FormLabelWidth() {
  const [automatic, setAutomatic] = useState(true);
  const [extra, setExtra] = useState(false);
  return (
    <Space direction="vertical" align="stretch">
      <Flex gap="md" align="center" wrap justify="center">
        <Switch checked={automatic} onChange={(event) => setAutomatic(event.target.checked)}>
          Automatic label widths
        </Switch>
        <Button variant="outline" onClick={() => setExtra(!extra)}>
          Toggle long label
        </Button>
      </Flex>
      <Form labelWidth={automatic ? 'auto' : 110}>
        <FormField label="Name">
          <Input name="name" />
        </FormField>
        <FormField label="Work email">
          <Input name="email" />
        </FormField>
        {extra && (
          <FormField label="Emergency contact number">
            <Input name="emergency" />
          </FormField>
        )}
      </Form>
    </Space>
  );
}

Extended features

extensions.tsx

import { Button, Flex, Form, FormErrorSummary, FormField, FormGroup, FormList, Input, Space } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <Form layout="vertical" onSubmit={(e) => e.preventDefault()}>
      <FormErrorSummary />
      <FormGroup legend="Contacts" description="Add, remove or reorder contacts.">
        <FormList name="contacts" defaultValue={['']}>
          {(fields, ops) => (
            <>
              {fields.map((field) => (
                <FormField key={field.key} label={`Contact ${field.index + 1}`} required>
                  <Flex gap="sm" align="start">
                    <Input
                      style={{ flex: 1, minWidth: 0 }}
                      name={`${field.name}.email`}
                      type="email"
                      value={field.value}
                      onChange={(e) => ops.update(field.index, e.target.value)}
                    />
                    <Button variant="ghost" onClick={() => ops.remove(field.index)}>
                      Remove
                    </Button>
                    {field.index > 0 && (
                      <Button
                        variant="ghost"
                        onClick={() => ops.move(field.index, field.index - 1)}
                      >
                        Move up
                      </Button>
                    )}
                  </Flex>
                </FormField>
              ))}
              <Button variant="outline" onClick={() => ops.add('')}>
                Add contact
              </Button>
            </>
          )}
        </FormList>
      </FormGroup>
      <Space>
        <Button type="submit">Validate</Button>
        <Button type="reset" variant="outline">
          Reset
        </Button>
      </Space>
    </Form>
  );
}

Form API

Property	Type	Default	Description
`layout`	`'horizontal' \| 'vertical'`	`'horizontal'`	Label and field layout
`labelWidth`	`number \| 'auto'`	`'auto'`	A pixel width, or auto to align all labels to the widest label
`labelAlign`	`'left' \| 'right'`	`'right'`	Label alignment
`disabled`	`boolean`	`false`	Disable interaction.
`ref`	`Ref<HTMLFormElement>`	—	Reference to the form

FormField API

Property	Type	Default	Description
`label`	`ReactNode`	—	Field label
`htmlFor`	`string`	Generated	The associated control ID; one field wraps one control or group
`required`	`boolean`	`false`	Require a non-empty value; compound controls validate once.
`help`	`ReactNode`	—	Supporting text below the control, included in the field layout
`error`	`ReactNode`	—	Error message, displayed instead of help
`labelWidth`	`number`	—	Override this field’s label width in pixels

Types

Import types when defining reusable component props or assembling options.

import type { FormProps, FormFieldProps } from '@ifhover/leaf-ui';

Usage notes

By default, all labels in one Form use the width of its widest label. Widths update when text, fonts or mounted fields change. Vertical layouts and narrow screens stack labels above fields. Standard form attributes such as action, method, onSubmit and onReset are supported.

Help and error messages occupy normal layout space and preserve the form gap before the next field. Wrapped text naturally adds height.

Read named controls with FormData. Use required, type and minLength for basic validation; errors appear beside their fields. Pass application or server errors through error. Set noValidate when handling validation yourself. FormData contains strings, does not build nested objects, and omits unchecked checkboxes. Reset controlled fields in application state.

Extension types

import type { FormGroupProps, FormListProps, FormListField, FormListOperations, FormErrorSummaryProps, FormError } from '@ifhover/leaf-ui';

FormGroupProps API

Property	Type	Default	Description
`legend`	`ReactNode`	—	Field group title
`description`	`ReactNode`	—	Supporting description

FormListProps API

Property	Type	Default	Description
`name`	`string`	Required	Required. Form field name
`value`	`readonly T[]`	—	Controlled value
`defaultValue`	`readonly T[]`	`[]`	Initial value, restored by uncontrolled form resets
`onChange`	`(values: T[]) => void`	—	Value change callback
`itemKey`	`(value: T) => string`	—	Return a stable identifier
`children`	`(fields: readonly FormListField<T>[], operations: FormListOperations<T>) => ReactNode`	Required	Required. Content or child items

FormListField API

Property	Type	Default	Description
`key`	`string`	Required	Required. Unique stable identifier
`index`	`number`	Required	Required. Current index, starting at zero
`name`	`string`	Required	Required. Form field name
`value`	`T`	Required	Required. Controlled value

FormListOperations API

Property	Type	Default	Description
`add`	`(value: T, index?: number) => void`	Required	Required. Insert a field; omitted index appends
`remove`	`(index: number \| readonly number[]) => void`	Required	Required. Remove one or multiple indices
`move`	`(from: number, to: number) => void`	Required	Required. Move fields preserving stable keys
`update`	`(index: number, value: T) => void`	Required	Required. Update field value

FormErrorSummaryProps API

Property	Type	Default	Description
`errors`	`readonly FormError[]`	—	Omitted collects field errors in this Form
`title`	`ReactNode`	—	Title content

FormError API

Property	Type	Default	Description
`fieldId`	`string`	Required	Required. Input id focused when error is clicked
`message`	`ReactNode`	Required	Required. Error content
`label`	`ReactNode`	—	Display label

React Hook Form integration

Install react-hook-form in your application. Use register with native inputs and Controller with components whose onChange returns a value. Leaf Form handles layout; the form library owns validation and state. Use noValidate to take over validation. FormList names are plain field names; use useFieldArray when React Hook Form manages the collection.

import { useForm, Controller } from 'react-hook-form';
import { Form, FormField, FormErrorSummary, Input, Select, Button } from '@ifhover/leaf-ui';

export function AccountForm() {
  const { register, control, handleSubmit, formState: { errors } } = useForm({ defaultValues: { email: '', role: '' } });
  return <Form noValidate onSubmit={handleSubmit(values => console.log(values))}>
    <FormErrorSummary />
    <FormField label="Email" error={errors.email?.message}>
      <Input {...register('email', { required: 'Enter an email' })} />
    </FormField>
    <Controller name="role" control={control} rules={{ required: 'Choose a role' }} render={({ field, fieldState }) =>
      <FormField label="Role" error={fieldState.error?.message}>
        <Select {...field} options={[{ value: 'editor', label: 'Editor' }]} />
      </FormField>}
    />
    <Button type="submit">Save</Button>
  </Form>;
}

FormValidationApi

Property	Type	Default	Description
`errors`	`Record<string, string>`	—	Required. Field-keyed errors for FormField.
`pending`	`boolean`	—	Required. Whether validation or submission is pending.
`setErrors`	`Dispatch<SetStateAction<Record<string, string>>>`	—	Required. Set server or business errors.
`handleSubmit`	`(event: FormEvent<HTMLFormElement>) => Promise<void>`	—	Required. Bind to Form.onSubmit.
`handleReset`	`(event: FormEvent<HTMLFormElement>) => void`	—	Required. Bind to Form.onReset to cancel requests and clear errors.
`cancel`	`() => void`	—	Required. Cancel the current request.
`clearErrors`	`(name?: string) => void`	—	Required. Clear one or all errors and cancel stale requests.

FormValidationOptions

Property	Type	Default	Description
`validate`	`( data: FormData, signal: AbortSignal, ) => Record<string, string> \| Promise<Record<string, string>>`	—	Required. Validate FormData with a cancellation signal; return field-keyed errors.
`onSubmit`	`(data: FormData, signal: AbortSignal) => void \| Promise<void>`	—	Submit after validation, respecting cancellation.
`onError`	`(error: unknown) => void`	—	Called on failure; the palette remains open with error feedback.
`focusError`	`boolean`	—	Focus the first invalid field.

#Form

#Submission and validation

#Label widths

#Extended features

#Form API

#FormField API

#Types

#Usage notes

#Extension types

#FormGroupProps API

#FormListProps API

#FormListField API

#FormListOperations API

#FormErrorSummaryProps API

#FormError API

#React Hook Form integration

#FormValidationApi

#FormValidationOptions