---
type: "TechArticle"
softwareVersion: "1.0.0"
url: "https://registry.docsloth.dev/components/tabs.html"
markdown: "https://registry.docsloth.dev/docs/tabs.md"
component: "tabs"
section: "interactive"
trust_class: "interactive"
implementation_status: "implemented_native"
renderer: "native block"
install: "docsloth component add @docsloth/tabs@1.0.0"
spec: "packages/contracts/component-specs/tabs.md"
props_schema: "packages/contracts/component-props/tabs.schema.json"
---

> Index: [Agent index](https://registry.docsloth.dev/llms.txt)

# tabs

Switch related presentations

| Field | Value |
| --- | --- |
| Trust class | interactive |
| Implementation status | implemented_native |
| Renderer | native block |
| Key prop (production schema) | tabs |
| Key prop (protocol fixture) | activeTab |
| Tools | select_tab |
| Package version | 1.0.0 |
| Package digest | sha256:2b5dfd26ede0e42e1f49f55a30405ae643e5dc18fe13460286d0ad1b7f2bcc22 |

## Install

```sh
docsloth component add @docsloth/tabs@1.0.0
```

Live package: sha256:2b5dfd26ede0e42e1f49f55a30405ae643e5dc18fe13460286d0ad1b7f2bcc22 with 2 file digest(s); the catalog entry is generated from the built package, not a placeholder.

## Props

The prop schema is normative in `packages/contracts/component-props/tabs.schema.json`.

| Prop | Type | Required | Constraints |
| --- | --- | --- | --- |
| `title` | string | no | maxLength: 160 |
| `tabs` | array<object> | yes | minItems: 1 |
| `default_id` | string | yes | maxLength: 256 |
| `sync_key` | string | no | maxLength: 256 |

Example props generated from this schema:

```json
{
  "title": "example-title",
  "tabs": [
    {
      "id": "example-id",
      "label": "example-label",
      "block_ids": [
        "00000000-0000-4000-8000-000000000000"
      ]
    }
  ],
  "default_id": "example-default_id",
  "sync_key": "example-sync_key"
}
```

Required props: tabs, default_id.

## Example

Example document IR (the block the renderer consumes):

```json
{
  "type": "tabs",
  "props": {
    "title": "Install",
    "active": 0
  },
  "children": [
    {
      "type": "prose",
      "props": {
        "label": "npm",
        "text": "npm add @docsloth/renderer"
      }
    },
    {
      "type": "code",
      "props": {
        "label": "pnpm",
        "language": "bash",
        "code": "pnpm add @docsloth/renderer"
      }
    }
  ]
}
```

Renderer HTML (entities decoded and wrapped for display):

```html
<div class="ds-tabs" data-component="tabs">
<div class="ds-tablist" role="tablist" aria-label="Install">
<button type="button" class="ds-tab" role="tab" id="b-tab-0" aria-controls="b-panel-0" aria-selected="true" tabindex="0">npm</button>
<button type="button" class="ds-tab" role="tab" id="b-tab-1" aria-controls="b-panel-1" aria-selected="false" tabindex="-1">pnpm</button>
</div>
<div class="ds-tabpanels">
<div class="ds-tabpanel" role="tabpanel" id="b-panel-0" aria-labelledby="b-tab-0" tabindex="0">
<div class="ds-prose">npm add @docsloth/renderer</div>
</div>
<div class="ds-tabpanel" role="tabpanel" id="b-panel-1" aria-labelledby="b-tab-1" tabindex="0">
<pre class="ds-code" data-lang="bash">
<code>pnpm add @docsloth/renderer</code>
</pre>
</div>
</div>
</div>
```

Preview (interface-only; the markup above is the same output):

The renderer resolves this component as a native block; the preview above is its real HTML output, and Markdown parity for native blocks is covered by the renderer test suite.

## Specification

Generated from `packages/contracts/component-specs/tabs.md`.

### Contract

Production props are normative in `../contracts/component-props/tabs.schema.json`. The corresponding `component-fixtures` manifest is only a minimal protocol fixture; use the production props schema when building the published package. The packaged artifact ships exactly its generated `component-package.json` manifest plus `props.schema.json` (the production props schema, copied byte-for-byte) and `spec.md` (this spec, copied byte-for-byte); it contains no executable payload, fallback implementation, Storybook, test suite, SSR harness or README. Rendering behavior and the acceptance cases below belong to the renderer and the repository tests, not to the package. Installation pins the package version and the digest of every shipped byte.

### Intended behavior

ARIA tabs, arrow keys, retain each panel in readable fallback; sync language preference within version.

### React host integration

The official React `Tabs` uses production `tabs`, `default_id`, `title` and `sync_key` props. It selects by ID across reordering; removing a selected tab restores the declared default (or the first tab when that default is absent). Arrow keys wrap, Home/End move to either end, and each tab is linked to its panel through ARIA attributes, following the [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).

A host supplies already-authorized, rendered release blocks with the exported `ComponentContentProvider` from `@docsloth/official-components/host`. Its `blocks` prop is a `ReadonlyMap<string, ReactNode>` and `releaseId` identifies the publication release. Tabs resolve only their declared `block_ids` from that map; missing blocks show “Content unavailable.” No block fetch or tool call occurs on selection. The JSON component props remain serializable; the provider is a React host API, separate from those props.

Tabs sharing a `sync_key` within one provider share the selected ID. Preferences stay in memory, are isolated from other providers, and reset when `releaseId` changes. The host must change that ID when switching releases. All panels render visibly on the server for readable no-JS fallback; hydration hides inactive panels while keeping their content mounted. This provider does not automatically wire the separate native document renderer or connected executor tools.

```tsx
<ComponentContentProvider releaseId={release.id} blocks={authorizedRenderedBlocks}>
  <Tabs tabs={tabDefinitions} default_id="npm" sync_key="package-manager" />
</ComponentContentProvider>
```

### Failure and fallback

Unknown selected ID resets to declared default, not arbitrary new tab.

### Required acceptance cases

No request or write occurs merely by selecting a tab. Also test empty data, loading, denied access, browser without JS, mobile 360px, keyboard navigation, dark mode and an explicit constrained agent tool call. The server independently authorizes capability requests; a package manifest cannot grant authority.

### Data and maintenance

Data bindings resolve from a specific publication/release vector and permitted fact/evidence graph. Configuration edits create versioned component patches. Update invalidation uses dependency IDs, never indiscriminate whole-page regeneration. Human-owned props survive automatic updates unless invalidated with an explicit conflict. Missing optional resources leave an honest inert/readable fallback, not a broken page or fake success.

### Cost and tools

Pure/local interaction must never invoke a model by accident. Any model, remote query or executor call must reserve approved budget before dispatch. Public visitors do not inherit owner resources. The component may call only named tools in its signed manifest with valid typed inputs. A cancelled job stops polling and closes resources. No component gets platform administration, raw credentials or an unlimited execution loop.

### Native renderer block

`packages/renderer` renders a `tabs` block from the document IR: children carry `props.label` and the renderer emits an accessible `role="tablist"` whose `role="tab"` buttons wire `aria-controls` to matching `role="tabpanel"` panels. Production props for a packaged instance remain normative in `../contracts/component-props/tabs.schema.json`.

#### Native block props

| prop | type | required | behaviour |
| --- | --- | --- | --- |
| `title` | string | no | Accessible name of the tablist (`aria-label`, default `Tabs`). |
| `active` | integer | no | Zero-based index selected by default; unknown values degrade to the first tab. |
| `activeTab` | string | no | Label or `props.id` of the selected tab; unknown ids degrade to the first tab. |
| `children` | DocBlock[] | yes | One panel per child; each child needs a non-empty `props.label`. A missing label degrades the whole block to the labelled fallback. |

Panels stay in the DOM (no `hidden`) so no-JS and agent readers see every presentation. The tab buttons are content labels, not chrome, so they are not marked `data-markdown-ignore`; Markdown flattens the block to `### <label>` subsections.

#### Example

```json
{
  "type": "tabs",
  "props": { "title": "Install", "active": 0 },
  "children": [
    { "type": "prose", "props": { "label": "npm", "text": "npm add @docsloth/renderer" } },
    { "type": "code", "props": { "label": "pnpm", "language": "bash", "code": "pnpm add @docsloth/renderer" } }
  ]
}
```

## Package manifest

Protocol fixture: `packages/contracts/component-fixtures/tabs.json`.

| Field | Value |
| --- | --- |
| Name | @docsloth/tabs |
| Version | 1.0.0 |
| Protocol | 1.x |
| License | Apache-2.0 |
| Runtime | react |
| Entry | dist/index.js |
| Recording policy | masked |
| Fallback | html, markdown, json |
| Network hosts | none |
| Production write | no |
| Max runtime seconds | 0 |
| Integrity | all zeros (protocol fixture placeholder) |

| Tool | Effect | Confirmation | Input |
| --- | --- | --- | --- |
| select_tab | read | no | value |

## Sources

| Source | Path |
| --- | --- |
| Component page | https://registry.docsloth.dev/components/tabs.html |
| Markdown twin | https://registry.docsloth.dev/docs/tabs.md |
| LLM index | https://registry.docsloth.dev/llms.txt |
| Specification | packages/contracts/component-specs/tabs.md |
| Prop schema | packages/contracts/component-props/tabs.schema.json |
| Protocol fixture | packages/contracts/component-fixtures/tabs.json |
| Catalog | packages/contracts/component-catalog.json |