# Fieldset

**`sonic-fieldset`** groups related form controls in a bordered container rendered as a native `<fieldset>`. Put fields in the default slot and title the group with a slotted `sonic-legend` or with the `label` and `description` shorthand. Pair the body with `sonic-form-layout` for responsive columns.

## Basic example

<sonic-code>
  <template>
    <sonic-fieldset>
      <sonic-legend label="Passenger contact"></sonic-legend>
      <sonic-form-layout>
        <sonic-input autocomplete="email" label="Email" name="email" type="email"></sonic-input>
        <sonic-input autocomplete="tel" label="Phone" name="phone" type="tel"></sonic-input>
      </sonic-form-layout>
    </sonic-fieldset>
  </template>
</sonic-code>

## Variant

With no `variant`, the fieldset is `default` (bordered). `ghost` and `shadow` hide the border; `shadow` adds `--sc-shadow-lg`.

<sonic-code>
  <template>
    <div class="grid gap-4">
      <sonic-fieldset variant="default">
        <sonic-legend label="Default"></sonic-legend>
        <sonic-input label="Field" name="a"></sonic-input>
      </sonic-fieldset>
      <sonic-fieldset variant="ghost">
        <sonic-legend label="Ghost"></sonic-legend>
        <sonic-input label="Field" name="b"></sonic-input>
      </sonic-fieldset>
      <sonic-fieldset variant="shadow">
        <sonic-legend label="Shadow"></sonic-legend>
        <sonic-input label="Field" name="c"></sonic-input>
      </sonic-fieldset>
    </div>
  </template>
</sonic-code>

## Tight

`tight` removes horizontal padding, side borders and rounding, for a flat strip inside a parent.

<sonic-code>
  <template>
    <sonic-fieldset tight variant="ghost">
      <sonic-legend label="Tight fieldset"></sonic-legend>
      <sonic-input label="Field" name="tight"></sonic-input>
    </sonic-fieldset>
  </template>
</sonic-code>

## Legend

`sonic-legend` takes `label` and `description`, or custom markup in its default slot with `sonic-legend-description` for the secondary line. `iconName` adds a leading `sonic-icon`. **`label` and `description` are rendered as HTML**: pass trusted content only.

<sonic-code>
  <template>
    <div class="grid gap-4">
      <sonic-fieldset>
        <sonic-legend label="Attributes" description="Short description via attributes"></sonic-legend>
        <sonic-input label="Field" name="attr"></sonic-input>
      </sonic-fieldset>
      <sonic-fieldset>
        <sonic-legend iconLibrary="iconoir" iconName="pin-alt">
          Custom title in the default slot
          <sonic-legend-description>Description via sonic-legend-description</sonic-legend-description>
        </sonic-legend>
        <sonic-input label="Field" name="slot"></sonic-input>
      </sonic-fieldset>
    </div>
  </template>
</sonic-code>

## Shorthand legend

When `label` is set on `sonic-fieldset`, it renders the `sonic-legend` itself and forwards `description` · `iconName` · `iconLibrary` · `iconPrefix`. Do not also slot a `sonic-legend`, or the group gets two titles.

<sonic-code>
  <template>
    <sonic-fieldset
      label="Crew profile"
      description="Basic crew member fields"
      iconLibrary="iconoir"
      iconName="user"
    >
      <sonic-input label="Display name" name="display_name"></sonic-input>
    </sonic-fieldset>
  </template>
</sonic-code>

## Legend actions

`slot="suffix"` on `sonic-legend` aligns menus or icon buttons to the end of the title row.

<sonic-code>
  <template>
    <sonic-fieldset>
      <sonic-legend label="Passenger details">
        <sonic-pop class="inline-block" slot="suffix">
          <sonic-button shape="circle" variant="ghost">
            <sonic-icon library="iconoir" size="lg" name="more-vert"></sonic-icon>
          </sonic-button>
          <sonic-menu slot="content" minWidth="12rem">
            <sonic-menu-item>Legal notice</sonic-menu-item>
            <sonic-menu-item>Terms of use</sonic-menu-item>
          </sonic-menu>
        </sonic-pop>
      </sonic-legend>
      <sonic-form-layout>
        <sonic-input autocomplete="family-name" label="Last name" name="last_name"></sonic-input>
        <sonic-input autocomplete="given-name" label="First name" name="first_name"></sonic-input>
      </sonic-form-layout>
    </sonic-fieldset>
  </template>
</sonic-code>

<sonic-alert status="warning" label="Disabled state and form association" text="Both attributes are set on the inner native fieldset only. Slotted Concorde fields are not disabled or re-associated by them: set disabled on each field instead."></sonic-alert>

## API reference

### `sonic-fieldset`

| Attribute | Values | Description |
|----------|---------|-------------|
| `variant` | `default` · `ghost` · `shadow` (default `default`) | Border and shadow treatment |
| `tight` | boolean | Removes horizontal padding, side borders and rounding |
| `label` | string | Shorthand title; renders a `sonic-legend` when set |
| `description` | string | Shorthand description (HTML) |
| `iconName` | string | Shorthand legend icon `name` |
| `iconLibrary` | string | Shorthand legend icon `library` |
| `iconPrefix` | string | Shorthand legend icon `prefix` |
| `disabled` | boolean | Sets `disabled` on the inner native `<fieldset>` |
| `form` | string | Sets `form` on the inner native `<fieldset>` |
| `dataProvider` | string | Publisher key; matching publisher fields (e.g. `label`) fill the properties |

| Slot | Description |
|------|-------------|
| *(default)* | Optional `sonic-legend`, then the grouped fields |

### `sonic-legend`

| Attribute | Values | Description |
|----------|---------|-------------|
| `label` | string | Title (HTML) |
| `description` | string | Description (HTML), wrapped in `sonic-legend-description` |
| `iconName` | string | Leading `sonic-icon` `name` |
| `iconLibrary` | string | Icon `library` |
| `iconPrefix` | string | Icon `prefix` |
| `forceAutoFill` | boolean | Lets a `label` or `description` set as a property override the attribute value |

| Slot | Description |
|------|-------------|
| *(default)* | Custom title and `sonic-legend-description` |
| `suffix` | Trailing actions (menus, icon buttons) |

### `sonic-legend-description`

No attributes. The default slot holds the muted line under the legend title.