Form

Headless form primitives that handle the boring parts: matching label’s htmlFor to the control’s id, wiring aria-describedby to descriptions and error messages, toggling aria-invalid / aria-required / disabled, and exposing data-invalid / data-required / data-disabled for styling.

You own the inputs — Form.Control clones a single child and injects the right attributes. Validation logic is yours; the Form simply renders Form.Error when the parent Form.Field is marked invalid.

Features

Example

import { Form } from '@wire-ui/react'
 
<Form.Root onSubmit={handleSubmit}>
<Form.Field name="email" invalid={emailInvalid} required>
<Form.Label>Email</Form.Label>
<Form.Control>
  <input type="email" />
</Form.Control>
<Form.Description>We'll send a magic link.</Form.Description>
<Form.Error>Please enter a valid email address.</Form.Error>
</Form.Field>
<button type="submit">Submit</button>
</Form.Root>

import { useState } from 'react'
import { Form } from '@wire-ui/react'
 
const labelCls = 'text-sm font-medium text-black'
const fieldCls = 'w-full rounded-[8px] border border-black bg-white px-3 py-2 text-sm text-black outline-none focus:ring-2 focus:ring-black focus:ring-offset-1 data-[invalid]:ring-2 data-[invalid]:ring-black disabled:opacity-50'
const descCls = 'text-xs text-[#6b7280]'
const errorCls = 'text-xs font-medium text-black'
 
function MyForm() {
  const [email, setEmail] = useState('not-an-email')
  const emailInvalid = !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
 
  return (
    <Form.Root className="flex w-80 flex-col gap-4">
      <Form.Field name="email" invalid={emailInvalid} required className="flex flex-col gap-1.5">
        <Form.Label className={labelCls}>Email</Form.Label>
        <Form.Control>
          <input
            type="email"
            value={email}
            onChange={(e) => setEmail(e.target.value)}
            className={fieldCls}
          />
        </Form.Control>
        <Form.Description className={descCls}>We'll send a magic link.</Form.Description>
        <Form.Error className={errorCls}>Please enter a valid email address.</Form.Error>
      </Form.Field>
      <button
        type="submit"
        disabled={emailInvalid}
        className="cursor-pointer rounded-[8px] border border-black bg-black px-4 py-2 text-sm font-medium text-white hover:bg-[#333] disabled:cursor-not-allowed disabled:opacity-50"
      >
        Submit
      </button>
    </Form.Root>
  )
}

Validation & error API

Validation in wire-ui Form is bring-your-own: derive an invalid boolean for each field and pass it to Form.Field. The Field is the source of truth — toggling invalid on the Field flips aria-invalid and data-invalid on the wrapped control, and conditionally renders Form.Error.

const emailInvalid = !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
 
<Form.Field name="email" invalid={emailInvalid} required>
  <Form.Label>Email</Form.Label>
  <Form.Control>
    <input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
  </Form.Control>
  <Form.Error>Please enter a valid email address.</Form.Error>
</Form.Field>

By default Form.Error only renders when invalid is true. Pass forceMount to keep it mounted (useful for animations or reserving space):

<Form.Error forceMount className="
  data-[state=hidden]:opacity-0
  data-[state=visible]:opacity-100
">
  Please enter a valid email address.
</Form.Error>

For per-rule messages, branch on your own error state:

const error = !value ? 'Required.' : !validFormat ? 'Wrong format.' : null
 
<Form.Field invalid={!!error}>
  <Form.Control><input ... /></Form.Control>
  <Form.Error>{error}</Form.Error>
</Form.Field>

Combining with wire-ui inputs

Form.Control only clones the first React element child. Pair it with a native <input> for the simple case, or skip Form.Control entirely and wrap a wire-ui field component (Input.Root, Textarea.Root, etc.) which manages its own id/aria internally — Form.Field still provides layout, error rendering, and the data-invalid flag.

<Form.Field name="email" invalid={emailInvalid}>
  <Input.Root invalidType={emailInvalid ? 'email' : ''} errorMessage={{ email: '...' }}>
    <Input.Label>Email</Input.Label>
    <Input.Field type="email" />
    <Input.Error />
  </Input.Root>
</Form.Field>

Using data attributes

[data-invalid]  { /* error state */ }
[data-required] { /* required indicator */ }
[data-disabled] { opacity: 0.5; cursor: not-allowed; }

Root props

Form.Root accepts all standard <form> props. The element is rendered with noValidate to suppress browser-native validation popups; remove with noValidate={false} if you need them.

Field props

Label props

Control props

Error props

Data attributes

Accessibility

• Form.Label automatically points to the control via htmlFor = control id.
• Form.Control sets aria-invalid, aria-required, and aria-describedby that references both the Description and Error ids when they’re present.
• Form.Error is rendered with role="alert" so screen readers announce it when it appears.
• Form.Root uses noValidate — combine with onSubmit to handle validation yourself.

Keyboard Interactions