# Data components

> Group content, display sortable tables, and reveal controlled detail.

Canonical: https://natui.dev/docs/components/data

## Section [#section]

Groups children under optional `header` and `footer` text.

### SectionProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `header` | `string \| undefined` | No |  |
| `footer` | `string \| undefined` | No |  |
| `children` | `ReactNode` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Section header="Identity" footer="All fields are required.">
  <TextField value={name} onChange={setName} />
</Section>
```

Sections can appear in lists or ordinary layout containers. On Windows, rows nested inside a list section do not participate in the outer list's row selection.

## Table [#table]

Tables receive serializable columns and rows. Cells are strings keyed by column.

### TableProps

A sortable, selectable table with data-driven columns and string cells.
The host never sorts: a header click emits onSortChange (request
semantics); the app re-sorts `rows` and echoes the new `sort`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | `TableColumnSpec[]` | Yes |  |
| `rows` | `TableRowSpec[]` | Yes |  |
| `value` | `string \| string[] \| null \| undefined` | No | Controlled selection over row ids; present (even null) = selectable. |
| `selectionMode` | `"single" \| "multiple" \| undefined` | No |  |
| `sort` | `SortDescriptor \| undefined` | No |  |
| `onChange` | `((value: string \| string[] \| null) => void) \| undefined` | No |  |
| `onSortChange` | `((sort: SortDescriptor) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Table
  columns={[
    { key: 'name', label: 'Name' },
    { key: 'status', label: 'Status', sortable: false },
  ]}
  rows={[
    { id: 'one', cells: { name: 'Aurora', status: 'Active' } },
  ]}
  value={selection}
  selectionMode="single"
  sort={sort}
  onChange={setSelection}
  onSortChange={setSort}
/>
```

The host never sorts rows. A header interaction requests a new `SortDescriptor`; the application sorts its data, provides the reordered rows, and echoes the descriptor.

On macOS 14.0 through 14.3, NatUI uses a list-based table fallback because the dynamic table API requires macOS 14.4.

## DisclosureGroup [#disclosuregroup]

Shows or hides child content using a controlled Boolean value.

### DisclosureGroupProps

Always-controlled disclosure; `value` is the expanded state.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes |  |
| `value` | `boolean` | Yes |  |
| `onChange` | `((expanded: boolean) => void) \| undefined` | No |  |
| `children` | `ReactNode` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<DisclosureGroup label="Details" value={expanded} onChange={setExpanded}>
  <Text>Additional information</Text>
</DisclosureGroup>
```

Disclosure state is always controlled. If React does not accept a native expansion change, NatUI corrects the host back to the current prop.