---
title: Tabs
description: Switch between bands of content that a reader takes one at a time.
---

A tabs block holds named tabs, each with any block or zone. The reader opens one
tab at a time. Use it for a record page with more than one band of content: an
issue's overview, its links, and its recipients.

Tabs switch between different content. To switch one list between values of one
field, use the [segments block](/reference/blocks/segments) instead.

The active tab is local to the renderer. It does not enter the URL, and a tab
change fetches nothing: every tab's content arrives with the view. A zone inside
a tab refreshes on its own state, and a zone in a closed tab does not fetch until
the tab opens.

## API

```ts
tabs(items: TabBuilder[]): TabsBuilder
tab(name: string, title: string): TabBuilder
```

| Method on `tabs` | Input                   | Result                                            |
| ---------------- | ----------------------- | ------------------------------------------------- |
| `setInitial`     | `string`                | Opens the named tab first.                        |
| `setWidth`       | `"full" \| "condensed"` | Stretches the tabs across the list, or hugs them. |
| `setDensity`     | `"compact"`             | Draws smaller tabs.                               |

| Method on `tab` | Input                                          | Result                                         |
| --------------- | ---------------------------------------------- | ---------------------------------------------- |
| `setIcon`       | `string`                                       | Adds an icon beside the title.                 |
| `setCount`      | `number`, `{ tone?: Tone; variant?: "badge" }` | Adds a count, as muted text or as a badge.     |
| `setContent`    | `Producer[]`                                   | Sets what the tab holds. Replaces the content. |

Properties that you do not set are not included in the protocol output. A block
with no tab, two tabs with one name, or an initial tab the block does not hold
fails at resolve.

## Basic tabs

Pass the tabs in their display order. The first one opens.

<BacklitExample path="tabs/basic" view="detail" />

## Initial tab

Name the tab that opens first.

<BacklitExample path="tabs/initial" view="detail" />

## Icon and count

A tab can carry an icon and a count. The renderer formats the count in the
client's locale. Without a variant the count draws as muted text; `badge` draws
it as a pill in its tone.

<BacklitExample path="tabs/count" view="detail" />

## Width

`full` stretches the tabs across the list. `condensed` hugs their content, which
is the default.

<BacklitExample path="tabs/full" view="detail" />

## Density

`compact` draws smaller tabs, for a header that must not dominate the content.

<BacklitExample path="tabs/compact" view="detail" />