# Field

Links a label, description, and error message to a control.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Field.tsx)

## Overview

A field links a label, description, and error message to the control inside it.

## Examples

### Basic

```tsx
import { Field, TextInput } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <TextInput.Group>
        <TextInput.Control placeholder="alice@example.com" type="email" />
      </TextInput.Group>
      <Field.Description>Used for receipts.</Field.Description>
    </Field.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Basic.tsx)

### Invalid

Set `invalid` to fill the control red and show a matching `Field.Error` in place of the description.

```tsx
import { Field, TextInput } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Field.Root invalid>
      <Field.Label>Invalid</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="alice" type="email" />
      </TextInput.Group>
      <Field.Description>Used for receipts.</Field.Description>
      <Field.Error match>Enter a valid email.</Field.Error>
    </Field.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Invalid.tsx)

### Success

Set `success` to end a text field with a check, and to set the description in the positive color.

```tsx
import { Field, TextInput } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Field.Root success>
      <Field.Label>Success</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="alice@example.com" type="email" />
      </TextInput.Group>
    </Field.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Success.tsx)

### Secondary Label

Put a `Field.SecondaryLabel` inside `Field.Label` for a qualifier at the end of the label row, such as Optional. It joins the control's accessible name.

```tsx
import { Field, style, TextInput } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>
        Memo <Field.SecondaryLabel>Optional</Field.SecondaryLabel>
      </Field.Label>
      <TextInput.Group>
        <TextInput.Control placeholder="What is it for?" />
      </TextInput.Group>
      <Field.Description>Only you and Maya can see this</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/SecondaryLabel.tsx)

### Size

Set `size` to `medium` (default) or `large`. A large field sets the label in the regular weight with its secondary label beside it, sets the description at 14px, and insets a text field or textarea 20px.

```tsx
import { Field, style, Textarea, TextInput } from '@tempoxyz/ds'

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root size="large">
        <Field.Label>
          Display name<Field.SecondaryLabel>Optional</Field.SecondaryLabel>
        </Field.Label>
        <TextInput.Group>
          <TextInput.Control placeholder="Maya Chen" />
        </TextInput.Group>
        <Field.Description>Shown to people you pay</Field.Description>
      </Field.Root>
      <Field.Root size="large">
        <Field.Label>
          Bio<Field.SecondaryLabel>Optional</Field.SecondaryLabel>
        </Field.Label>
        <Textarea placeholder="A few words about you" rows={2} />
        <Field.Description>Up to 160 characters</Field.Description>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '24',
    gridTemplateColumns: 'repeat(auto-fill, minmax(min(280px, 100%), 1fr)) !custom',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Size.tsx)

### Disabled

```tsx
import { Field, TextInput } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Field.Root disabled>
      <Field.Label>Disabled</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="Locked" />
      </TextInput.Group>
    </Field.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Disabled.tsx)

### Item

Wrap a checkbox or radio and its `Field.Label` in `Field.Item` to put them on one row.

```tsx
import { Checkbox, Field } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Field.Root>
      <Field.Item>
        <Checkbox defaultChecked />
        <Field.Label>Item with a checkbox</Field.Label>
      </Field.Item>
    </Field.Root>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Field/Item.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Field } from '@tempoxyz/ds'

<Field.Root>
  <Field.Label>
    <Field.SecondaryLabel />
  </Field.Label>
  <Field.Item />
  <Field.Description />
  <Field.Error />
</Field.Root>
```

## Guidelines

### When to Use

* Label an input control, such as [TextInput](/docs/components/text-input), [AmountInput](/docs/components/amount-input), [Textarea](/docs/components/textarea), [Select](/docs/components/select), or [Combobox](/docs/components/combobox).
* Attach a hint or an error to that control.
* Put a [Checkbox](/docs/components/checkbox) or radio on one row with its label through `Field.Item`.
* Label a [Switch](/docs/components/switch) above it, with its description below.

### When Not to Use

* Use [Fieldset](/docs/components/fieldset) to name a group of related fields, such as a billing address.
* Use [ListGroup](/docs/components/list-group) for read-only details.
* Use an [Alert](/docs/components/alert) above the form to summarize a failed submission.

### Give Every Control a Visible Label

**Do:** Name the control with a `Field.Label` and put the format in the description.

```tsx
/**
 * Do example for "Give Every Control a Visible Label" on the Field page.
 * Name the control with a `Field.Label` and put the format in the description.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Recipient</Field.Label>
      <TextInput.Group>
        <TextInput.Control placeholder="0x…" />
      </TextInput.Group>
      <Field.Description>A Tempo address that starts with 0x.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

**Don't:** Use the placeholder as the only label.

```tsx
/**
 * Don't example for "Give Every Control a Visible Label" on the Field page.
 * Don't use the placeholder as the only label.
 * @module
 */
import { style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <TextInput.Group {...styles.group()}>
      <TextInput.Control aria-label="Recipient" placeholder="Recipient address" />
    </TextInput.Group>
  )
}

namespace styles {
  export const group = style({ width: '100% !custom' })
}
```

### Keep Hints in the Description

Use `Field.Description` for one fact about the value, such as a format or a limit. Keep the label to the name of the value.

**Do:** Put the limit in `Field.Description` below the control.

```tsx
/**
 * Do example for "Keep Hints in the Description" on the Field page.
 * Put the limit in `Field.Description` below the control.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Key name</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="Payroll server" />
      </TextInput.Group>
      <Field.Description>Up to 32 letters, numbers, or spaces.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

**Don't:** Pack formats and limits into the label.

```tsx
/**
 * Don't example for "Keep Hints in the Description" on the Field page.
 * Don't pack formats and limits into the label.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <Field.Label>Key name (up to 32 letters, numbers, or spaces)</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="Payroll server" />
      </TextInput.Group>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

### Write Errors That Say How to Fix the Value

Start the `Field.Error` with a verb, such as Enter or Choose, and include the limit, such as Enter an amount up to 250.00 USDC. A shown error replaces the description, so repeat any limit the error depends on.

**Do:** Say what the value needs, such as the https\:// scheme.

```tsx
/**
 * Do example for "Write Errors That Say How to Fix the Value" on the Field page.
 * Say what the value needs, such as the https:// scheme.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <Field.Label>Webhook URL</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="http://api.example.com/hooks" type="url" />
      </TextInput.Group>
      <Field.Error match>Enter a URL that starts with https://.</Field.Error>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

**Don't:** Show a generic message such as Invalid input.

```tsx
/**
 * Don't example for "Write Errors That Say How to Fix the Value" on the Field page.
 * Don't show a generic message such as Invalid input.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <Field.Label>Webhook URL</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="http://api.example.com/hooks" type="url" />
      </TextInput.Group>
      <Field.Error match>Invalid input.</Field.Error>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

### Validate When the Value Is Complete

`Field.Root` validates on submit, then on each change after a failed submit. For format checks, such as a URL, set `validationMode="onBlur"`. Pass `validate` for custom rules. If another library owns validation, set `invalid`. See [Errors and Validation](/docs/patterns/errors-and-validation).

**Do:** Leave a partial value unmarked until focus leaves the field.

```tsx
/**
 * Do example for "Validate When the Value Is Complete" on the Field page.
 * Leave a partial value unmarked until focus leaves the field.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root validationMode="onBlur" {...styles.field()}>
      <Field.Label>Webhook URL</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="https://api.exa" type="url" />
      </TextInput.Group>
      <Field.Description>Starts with https://.</Field.Description>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

**Don't:** Flag a format error before the value is complete.

```tsx
/**
 * Don't example for "Validate When the Value Is Complete" on the Field page.
 * Don't flag a format error before the value is complete.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <Field.Label>Webhook URL</Field.Label>
      <TextInput.Group>
        <TextInput.Control defaultValue="https://api.exa" type="url" />
      </TextInput.Group>
      <Field.Error match>Enter a URL that starts with https://.</Field.Error>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

### Reserve Success for Verified Values

Set `success` only after the app checks the value, such as an address that resolves to a contact. It sets no ARIA state, so state the result in the description too.

**Do:** Mark only the checked value, and state the result in the description.

```tsx
/**
 * Do example for "Reserve Success for Verified Values" on the Field page.
 * Mark only the checked value, and state the result in the description.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.form()}>
      <Field.Root success>
        <Field.Label>Recipient address</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="0x8f3a…12c4" />
        </TextInput.Group>
        <Field.Description>Matches your contact Alice Chen.</Field.Description>
      </Field.Root>
      <Field.Root>
        <Field.Label>Memo</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="Rent for May" />
        </TextInput.Group>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const form = style({ display: 'grid', gap: '16', width: '100% !custom' })
}
```

**Don't:** Mark every filled field successful.

```tsx
/**
 * Don't example for "Reserve Success for Verified Values" on the Field page.
 * Don't turn every filled field green.
 * @module
 */
import { Field, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.form()}>
      <Field.Root success>
        <Field.Label>Recipient address</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="0x8f3a…12c4" />
        </TextInput.Group>
      </Field.Root>
      <Field.Root success>
        <Field.Label>Memo</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="Rent for May" />
        </TextInput.Group>
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const form = style({ display: 'grid', gap: '16', width: '100% !custom' })
}
```

## Accessibility

A field connects a control to its label, description, and error. See [Accessibility](/docs/foundations/accessibility) for the baseline.

### Semantics

* **Field.Label (label):** Names the control. A click focuses or toggles it.
* **Field.Description (aria-describedby):** Read after the control's name.
* **Field.Error (aria-describedby):** Once shown, read after the description.
* **Invalid State (aria-invalid):** Set on failed validation or `invalid`.
* **Disabled (disabled):** Disables the control and dims the label and description.
* **Field.Item:** Labels one checkbox or radio inside a group.

### Your Responsibilities

* **Label Every Control (Field.Label):** A placeholder disappears once the reader types, so it can't replace a label.
* **Explain the Fix:** State the fix in the error, not only the problem, such as "Enter an email address."
* **Focus the First Error:** The error is not a live region. If a submit fails, focus the first invalid field.
* **Confirm Success in Text (success):** The `success` check sets no ARIA state and isn't announced. Confirm a verified value in text.
* **State Requirements:** State requirements and formats in text, such as "(required)" in the label, not only with a symbol.
* **Label a Date Picker Trigger (aria-labelledby):** `Field.Label` doesn't name a [DatePicker](/docs/components/date-picker) trigger. Point `aria-labelledby` at a visible label.

## Related

[TextInput](/docs/components/text-input)

Use for single-line text.

[Fieldset](/docs/components/fieldset)

Use for grouping fields under a legend.

[Textarea](/docs/components/textarea)

Use for multi-line text.

[Forms](/docs/patterns/forms)

Covers laying out and submitting forms.

[Errors and Validation](/docs/patterns/errors-and-validation)

Covers when and how to show errors.
