# Fieldset

Groups related fields under a shared legend.

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

## Overview

A fieldset groups related fields under a legend in a native `<fieldset>`.

## Examples

### Basic

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

export function Demo() {
  return (
    <Fieldset.Root {...styles.group()}>
      <Fieldset.Legend>Legal name</Fieldset.Legend>
      <Name label="First name" />
      <Name label="Last name" />
    </Fieldset.Root>
  )
}

function Name(props: { label: string }) {
  return (
    <Field.Root>
      <Field.Label>{props.label}</Field.Label>
      <TextInput.Group>
        <TextInput.Control />
      </TextInput.Group>
    </Field.Root>
  )
}

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

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

### Disabled

Set `disabled` to disable every control in the group.

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

export function Demo() {
  return (
    <Fieldset.Root disabled {...styles.group()}>
      <Fieldset.Legend>Legal name</Fieldset.Legend>
      <Field.Root>
        <Field.Label>First name</Field.Label>
        <TextInput.Group>
          <TextInput.Control />
        </TextInput.Group>
      </Field.Root>
      <Field.Root>
        <Field.Label>Last name</Field.Label>
        <TextInput.Group>
          <TextInput.Control />
        </TextInput.Group>
      </Field.Root>
    </Fieldset.Root>
  )
}

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

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

## Anatomy

Import the component and assemble its parts.

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

<Fieldset.Root>
  <Fieldset.Legend />
  <Field.Root />
</Fieldset.Root>
```

## Guidelines

### When to Use

* Group fields that describe one thing, such as an address.
* Name a set of radios or checkboxes with one question.

### When Not to Use

* Use [Field](/docs/components/field) alone for a single control. A fieldset around one field repeats its label.
* Use a heading for a page section with no form controls.
* Use [Stepper](/docs/components/stepper) to split a long form into steps, not many fieldsets on one screen.

### Write the Legend as the Group's Topic

* **Radio group:** Write a question that ends with a question mark, such as How often should we pay you?
* **Set of fields:** Write a noun without a colon, such as Billing address.

Keep each field's own `Field.Label`, and don't repeat the legend in it.

**Do:** Name the group in the legend and each value in its label.

```tsx
/**
 * Do example for "Write the Legend as the Group's Topic" on the Fieldset page.
 * Name the group in the legend and each value in its label.
 * @module
 */
import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Fieldset.Root {...styles.group()}>
      <Fieldset.Legend>Billing address</Fieldset.Legend>
      <Field.Root>
        <Field.Label>Street</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="350 Mission St" />
        </TextInput.Group>
      </Field.Root>
      <Field.Root>
        <Field.Label>City</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="San Francisco" />
        </TextInput.Group>
      </Field.Root>
    </Fieldset.Root>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
}
```

**Don't:** Repeat the legend in every field label.

```tsx
/**
 * Don't example for "Write the Legend as the Group's Topic" on the Fieldset page.
 * Don't repeat the legend in every field label.
 * @module
 */
import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Fieldset.Root {...styles.group()}>
      <Fieldset.Legend>Billing address</Fieldset.Legend>
      <Field.Root>
        <Field.Label>Billing address street</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="350 Mission St" />
        </TextInput.Group>
      </Field.Root>
      <Field.Root>
        <Field.Label>Billing address city</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="San Francisco" />
        </TextInput.Group>
      </Field.Root>
    </Fieldset.Root>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
}
```

### Disable the Group, Not Each Field

Set `disabled` on `Fieldset.Root` to disable every control inside. State the reason above the group, such as Billing details are locked while a payment is pending.

**Do:** Disable the fieldset and say why above it.

```tsx
/**
 * Do example for "Disable the Group, Not Each Field" on the Fieldset page.
 * Disable the fieldset and say why above it.
 * @module
 */
import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <p {...styles.reason()}>Billing details are locked while a payment is pending.</p>
      <Fieldset.Root disabled {...styles.group()}>
        <Fieldset.Legend>Billing address</Fieldset.Legend>
        <Field.Root>
          <Field.Label>Street</Field.Label>
          <TextInput.Group>
            <TextInput.Control defaultValue="350 Mission St" />
          </TextInput.Group>
        </Field.Root>
        <Field.Root>
          <Field.Label>City</Field.Label>
          <TextInput.Group>
            <TextInput.Control defaultValue="San Francisco" />
          </TextInput.Group>
        </Field.Root>
      </Fieldset.Root>
    </div>
  )
}

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

  export const reason = style({ color: 'content.secondary', margin: '0', typography: 'body.b2' })

  export const stack = style({
    display: 'grid',
    gap: '16',
    maxWidth: '320px !custom',
    width: '100% !custom',
  })
}
```

**Don't:** Disable a group without a reason.

```tsx
/**
 * Don't example for "Disable the Group, Not Each Field" on the Fieldset page.
 * Don't disable a group without a reason.
 * @module
 */
import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Fieldset.Root disabled {...styles.group()}>
      <Fieldset.Legend>Billing address</Fieldset.Legend>
      <Field.Root>
        <Field.Label>Street</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="350 Mission St" />
        </TextInput.Group>
      </Field.Root>
      <Field.Root>
        <Field.Label>City</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="San Francisco" />
        </TextInput.Group>
      </Field.Root>
    </Fieldset.Root>
  )
}

namespace styles {
  export const group = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
}
```

### Keep Groups Flat and Short

Screen readers announce every legend of nested fieldsets as focus moves in. Put groups one after another, each with its own legend. If a group grows past five or six fields, split it under a second legend.

**Do:** Place short groups one after another.

```tsx
/**
 * Do example for "Keep Groups Flat and Short" on the Fieldset page.
 * Place short groups one after another.
 * @module
 */
import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'

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

namespace styles {
  export const form = style({
    display: 'grid',
    gap: '24',
    maxWidth: '320px !custom',
    width: '100% !custom',
  })

  export const group = style({ rowGap: '12' })
}
```

**Don't:** Nest one fieldset inside another.

```tsx
/**
 * Don't example for "Keep Groups Flat and Short" on the Fieldset page.
 * Don't nest one fieldset inside another.
 * @module
 */
import { Field, Fieldset, style, TextInput } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Fieldset.Root {...styles.outer()}>
      <Fieldset.Legend>Destination</Fieldset.Legend>
      <Field.Root>
        <Field.Label>Address</Field.Label>
        <TextInput.Group>
          <TextInput.Control defaultValue="0x8f3a…12c4" />
        </TextInput.Group>
      </Field.Root>
      <Fieldset.Root {...styles.group()}>
        <Fieldset.Legend>Payment</Fieldset.Legend>
        <Field.Root>
          <Field.Label>Memo</Field.Label>
          <TextInput.Group>
            <TextInput.Control defaultValue="Rent for May" />
          </TextInput.Group>
        </Field.Root>
      </Fieldset.Root>
    </Fieldset.Root>
  )
}

namespace styles {
  export const group = style({ rowGap: '12' })

  export const outer = style({ maxWidth: '320px !custom', rowGap: '12', width: '100% !custom' })
}
```

## Accessibility

A fieldset renders a native `<fieldset>` named by its legend. Screen readers read the legend before the controls.

### Semantics

* **Fieldset.Root (group):** A native fieldset with one name for related controls.
* **Fieldset.Legend (aria-labelledby):** Names the fieldset, as a div, not a native legend.
* **Disabled (disabled):** Disables every control inside and dims the labels.

### Your Responsibilities

* **Include a Legend (Fieldset.Legend):** Include a legend. Without one, the group has no accessible name.
* **Group Related Controls:** Group only related controls, such as radios or an address.
* **Render a Heading When Needed (render):** The legend is not a heading. If the group starts a section, render an `h2`.

## Related

[Field](/docs/components/field)

Use for labelling a single control.

[RadioGroup](/docs/components/radio-group)

Use for one choice from a group.

[CheckboxGroup](/docs/components/checkbox-group)

Use for several choices from a group.

[Forms](/docs/patterns/forms)

Covers laying out groups of fields.
