Forms

Overview

Cubby UI provides three components for building accessible forms: Form, Field, and Fieldset. These wrap Base UI's form primitives, providing native constraint validation, custom validation, accessible labeling, error display, and integration with third-party libraries.

Quick start


import { Button } from "@/components/ui/cubby-ui/button";
import { Field, FieldControl, FieldError, FieldLabel } from "@/components/ui/cubby-ui/field";
import { Form } from "@/components/ui/cubby-ui/form";
 
<Form onFormSubmit={(values) => console.log(values)}>
  <Field name="email">
    <FieldLabel>Email</FieldLabel>
    <FieldControl type="email" required />
    <FieldError match="valueMissing">Email is required</FieldError>
    <FieldError match="typeMismatch">Enter a valid email</FieldError>
  </Field>
  <Button type="submit">Submit</Button>
</Form>

Labeling form controls

Every form control needs an accessible label. The correct label component depends on the control type.

Input-type controls

Use FieldLabel to label these controls:

Input
Number Field
Combobox (when the input is outside the popup)
Checkbox
Radio
Switch

For Checkbox, Radio, and Switch, wrap the control inside FieldLabel for implicit labeling:


<Field name="terms">
  <FieldLabel>
    <Checkbox required />
    I accept the terms
  </FieldLabel>
</Field>

Trigger-based controls

These controls have their own label component. Do not use FieldLabel for them:

Select: use SelectLabel
Slider: use SliderLabel


<Field name="country">
  <Select items={countries} required>
    <SelectLabel>Country</SelectLabel>
    <SelectTrigger>
      <SelectValue placeholder="Select a country" />
    </SelectTrigger>
    <SelectContent>...</SelectContent>
  </Select>
  <FieldError />
</Field>

Descriptions

FieldDescription adds accessible helper text to any field, regardless of control type:


<Field name="timezone">
  <Select items={timezones}>
    <SelectLabel>Time zone</SelectLabel>
    <SelectTrigger>...</SelectTrigger>
    <SelectContent>...</SelectContent>
  </Select>
  <FieldDescription>Used for notifications and reminders</FieldDescription>
</Field>

Grouping controls with Fieldset

Use Fieldset with FieldsetLegend when a single label applies to multiple controls, such as radio groups, checkbox groups, or multi-thumb sliders. Compose with the render prop to merge the fieldset element with a group component:


<Field name="role">
  <Fieldset render={<RadioGroup defaultValue="member" />}>
    <FieldsetLegend>Role</FieldsetLegend>
    <FieldItem>
      <FieldLabel>
        <RadioGroupItem value="member" />
        Member
      </FieldLabel>
    </FieldItem>
    <FieldItem>
      <FieldLabel>
        <RadioGroupItem value="admin" />
        Admin
      </FieldLabel>
    </FieldItem>
  </Fieldset>
</Field>

Use FieldItem to wrap each individual option so it gets its own label and description.

Validation

Constraint validation

Use native HTML attributes on FieldControl (required, pattern, minLength, type, min, max, etc.) and FieldError to display the browser's native error message:


<Field name="website">
  <FieldLabel>Website</FieldLabel>
  <FieldControl type="url" required pattern="https?://.*" />
  <FieldError />
</Field>

Per-state custom messages

To override native messages (for i18n or branding), use multiple FieldError components with the match prop — each one renders only for the specified validity state:


<Field name="password">
  <FieldLabel>Password</FieldLabel>
  <FieldControl type="password" required minLength={8} />
  <FieldError match="valueMissing">Password is required</FieldError>
  <FieldError match="tooShort">Must be at least 8 characters</FieldError>
</Field>

Available match values: valueMissing, typeMismatch, patternMismatch, tooShort, tooLong, rangeUnderflow, rangeOverflow, stepMismatch, badInput, customError.

Custom validation

Use the validate prop on Field for custom logic. Supports async functions:


<Field
  name="username"
  validationMode="onChange"
  validationDebounceTime={300}
  validate={async (value) => {
    const taken = await checkUsername(value);
    return taken ? "Username is taken" : null;
  }}
>
  <FieldLabel>Username</FieldLabel>
  <FieldControl />
  <FieldError />
</Field>

Server-side validation

Pass errors from your server to Form's errors prop. Keys match field name attributes:


const [errors, setErrors] = React.useState({});
 
<Form
  errors={errors}
  onSubmit={async (event) => {
    event.preventDefault();
    const response = await submitToServer(new FormData(event.currentTarget));
    if (response.errors) setErrors(response.errors);
  }}
>
  <Field name="email">...</Field>
</Form>

Submitting data

Native onSubmit

Use onSubmit with FormData for standard form submission:


<Form onSubmit={(event) => {
  event.preventDefault();
  const formData = new FormData(event.currentTarget);
  // send formData
}} />

JavaScript object with onFormSubmit

Use onFormSubmit to receive values as a plain object. preventDefault is called automatically:


<Form onFormSubmit={(values) => {
  // values is { name: "...", email: "...", ... }
}} />

Third-party library integration

React Hook Form

Use Controller to bridge RHF state with Field's invalid, dirty, and touched props. Use onValueChange on FieldControl (not onChange) and match={!!error} on FieldError:


<Controller
  name="username"
  control={control}
  rules={{
    required: "This is a required field.",
    minLength: { value: 3, message: "At least 3 characters." },
  }}
  render={({
    field: { ref, name, value, onBlur, onChange },
    fieldState: { invalid, isTouched, isDirty, error },
  }) => (
    <Field name={name} invalid={invalid} touched={isTouched} dirty={isDirty}>
      <FieldLabel>Username</FieldLabel>
      <FieldControl
        ref={ref}
        value={value}
        onBlur={onBlur}
        onValueChange={onChange}
        placeholder="e.g. alice132"
      />
      <FieldError match={!!error}>{error?.message}</FieldError>
    </Field>
  )}
/>

For RHF to focus invalid fields, forward ref to the underlying control - typically via inputRef on wrapper components (Select, Switch, Checkbox, RadioGroup) or directly as ref on input-like components.

TanStack Form

Use form.Field (TanStack's field) to manage state, and Field (Cubby UI) for the UI. Note: the Base UI Form component isn't needed with TanStack Form - use a native <form> element instead.


import { useForm, revalidateLogic } from "@tanstack/react-form";
 
const form = useForm({
  defaultValues: { email: "" },
  onSubmit: ({ value }) => {
    // submit value
  },
  validationLogic: revalidateLogic({
    mode: "submit",
    modeAfterSubmission: "change",
  }),
  validators: {
    onDynamic: ({ value }) => {
      const errors: Record<string, string> = {};
      if (!value.email) errors.email = "Email is required";
      return Object.keys(errors).length === 0
        ? undefined
        : { form: errors, fields: errors };
    },
  },
});
 
<form
  onSubmit={(event) => {
    event.preventDefault();
    form.handleSubmit();
  }}
  noValidate
>
  <form.Field name="email">
    {(field) => (
      <Field
        name={field.name}
        invalid={!field.state.meta.isValid}
        dirty={field.state.meta.isDirty}
        touched={field.state.meta.isTouched}
      >
        <FieldLabel>Email</FieldLabel>
        <FieldControl
          value={field.state.value}
          onValueChange={field.handleChange}
          onBlur={field.handleBlur}
        />
        <FieldError match={!field.state.meta.isValid}>
          {field.state.meta.errors.join(",")}
        </FieldError>
      </Field>
    )}
  </form.Field>
</form>

Component reference

Component	Use for
Form	Form wrapper with `errors`, `onFormSubmit`, `validationMode`
Field	Field wrapper with label, control, description, error, validation
Fieldset	Grouping related fields with a shared legend

On this page