# Section

A compound layout for a topic of settings. `Section.Root` stacks groups; each `Section.Group` is named by the `Section.Title` in its `Section.Header`, above a `Section.Body` card holding `Section.Row`s (one setting each) or a `Section.Items` list of values. Each `Section.Group` is a `cl-section` size container that switches to a compact layout below 26rem; `sectionCompactStyles.hidden` and `.only` show or hide content inside a group at that width.

## Use for

- a settings page or profile section with rows of settings
- a row with a label, a value and an action, such as an Edit button
- a list of values, such as emails or devices, inside a settings card
- a row-level error message for a row without a form control

## Practices

- Do: Render `<Section.Error>{error}</Section.Error>` without a conditional. It opens and closes on its message.
- Do: Place `Section.Error` beside `Section.Item` inside `Section.Row`, not inside `Section.Content`.
- Do: Use `Section.Note` in place of `Section.Actions` when a row offers no action, to say why.
- Don't: Wrap `Section.Note` in `Section.Actions`. It holds its own trailing position.
- Don't: Swap rows for a loading state with a conditional in the view. Build a skeleton with `Skeleton` (`mosaic guides inspect skeletons`).

## API reference

### Section.Root

Renders a `section` that stacks groups.

Slot: `cl-section`

### Section.Group

A `role='group'` labelled by its `Section.Title`, unless `aria-label` or `aria-labelledby` is passed.

Slot: `cl-section-group`

### Section.Header

Holds the title, and optionally `Section.Content` and `Section.Actions` laid out for a header.

Slot: `cl-section-header`

### Section.Title

A `Heading` at the current heading level, at size `base`, truncated to one line. Generates an `id` inside a group so the group is named by it. Takes `Heading` props except `size`.

Slot: `cl-section-title`

### Section.Body

The card that holds rows or an items list.

Slot: `cl-section-body`

### Section.Row

One setting.

Slot: `cl-section-row`

### Section.Items

A `ul` of values. Each `Section.Item` inside renders as an `li` and carries `data-nested`.

Slot: `cl-section-items`

### Section.Item

Lays out media, content and actions on one line. Renders a `div`, or an `li` inside `Section.Items`.

Slot: `cl-section-item`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `wrap` | `boolean` | `false` | Lets the actions wrap under the content. Carries `data-wrap`. |

### Section.Media

A leading box for an avatar, logo or icon. Carries `data-size`.

Slot: `cl-section-media`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `SectionMediaSize` | `'md'` | `sm`, `md`, `lg` or `xl`. |

### Section.Content

Stacks the label and description. Carries `data-nested` inside `Section.Items`.

Slot: `cl-section-content`

### Section.Label

The row label. Its text truncates to one line; element children such as icons pass through.

Slot: `cl-section-label`

### Section.Description

Secondary text under the label.

Slot: `cl-section-description`

### Section.Actions

Trailing buttons or menu for the row.

Slot: `cl-section-actions`

### Section.Note

Static text in place of an action, stating why the row offers none. Truncated to one line.

Slot: `cl-section-note`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `React.ReactNode` |  | Renders in a leading slot (`cl-section-note-icon`) sized to the text, such as a lock. |

### Section.Error

A row-level message with `role='alert'`, for a row that holds no form control. Animates its height open and closed.

Slot: `cl-section-error`

## Examples

### A settings row

```tsx
<Section.Row>
  <Section.Item>
    <Section.Content>
      <Section.Label>{m.name.label}</Section.Label>
      <Section.Description>{name}</Section.Description>
    </Section.Content>
    <Section.Actions>{editButton}</Section.Actions>
  </Section.Item>
  <Section.Error>{error}</Section.Error>
</Section.Row>
```

## Related

- [Heading](/docs/components/heading.md)
- [Skeleton](/docs/components/skeleton.md)
- [Field](/docs/components/field.md)
