# 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.

Give every control a visible `Field.Label`. Base UI links it to the control.

## Examples

### Basic

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

export function Demo() {
  return (
    <Field.Root>
      <Field.Label>Email</Field.Label>
      <Input.Group>
        <Input.Control placeholder="alice@example.com" type="email" />
      </Input.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)

### Variant

Set `variant` to `default`, `stacked`, `card`, or `setting`. It defaults to `default`, and nested fields inherit it from a `Fieldset.Root`.

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

export function Demo() {
  return (
    <div {...styles.grid()}>
      <Field.Root>
        <Field.Label>Default</Field.Label>
        <Input.Group>
          <Input.Control placeholder="alice@example.com" type="email" />
        </Input.Group>
        <Field.Description>Used for receipts.</Field.Description>
      </Field.Root>
      <Field.Root variant="stacked">
        <Field.Label>Stacked</Field.Label>
        <Input.Group>
          <Input.Control placeholder="alice@example.com" type="email" />
        </Input.Group>
      </Field.Root>
      {(['small', 'medium', 'large'] as const).map((size) => (
        <Field.Root key={size} variant="card">
          <Field.Label>Card ({size})</Field.Label>
          <Input.Group size={size}>
            <Input.Prefix>$</Input.Prefix>
            <Input.Control defaultValue="250.00" />
            <Input.Suffix>USDC</Input.Suffix>
          </Input.Group>
        </Field.Root>
      ))}
      <Field.Root variant="setting">
        <Field.Label>Setting</Field.Label>
        <Field.Description>Swap incoming funds to USDC.</Field.Description>
        <Switch defaultChecked />
      </Field.Root>
    </div>
  )
}

namespace styles {
  export const grid = style({
    alignItems: 'start',
    display: 'grid',
    gap: '6',
    gridTemplateColumns: 'repeat(auto-fill, minmax(18rem, 1fr)) !custom',
  })
}
```

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

### Invalid

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

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

export function Demo() {
  return (
    <Field.Root invalid>
      <Field.Label>Invalid</Field.Label>
      <Input.Group>
        <Input.Control defaultValue="alice" type="email" />
      </Input.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 tint the control green.

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

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

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

### Disabled

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

export function Demo() {
  return (
    <Field.Root disabled>
      <Field.Label>Disabled</Field.Label>
      <Input.Group>
        <Input.Control defaultValue="Locked" />
      </Input.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 place 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)

## Guidelines

TODO: Write guidelines for Field.