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

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

# accordion

Progressive disclosure of optional detail

| Field | Value |
| --- | --- |
| Trust class | interactive |
| Implementation status | implemented_native |
| Renderer | native block |
| Key prop (production schema) | title |
| Key prop (protocol fixture) | no protocol fixture published |
| Tools | toggle |
| Package version | 1.0.0 |
| Package digest | sha256:320b0d6b28817df96a4f8b3274e151218c9f04c31862d4cd0d895397ee77258e |

## Install

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

Live package: sha256:320b0d6b28817df96a4f8b3274e151218c9f04c31862d4cd0d895397ee77258e 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/accordion.schema.json`.

| Prop | Type | Required | Constraints |
| --- | --- | --- | --- |
| `title` | string | no | maxLength: 160 |
| `open` | integer | no |  |

Example props generated from this schema:

```json
{
  "title": "FAQ",
  "open": 0
}
```

This schema requires no props beyond the component envelope.

## Example

Example document IR (the block the renderer consumes):

```json
{
  "type": "accordion",
  "props": {
    "title": "FAQ"
  },
  "children": [
    {
      "type": "prose",
      "props": {
        "label": "How is Markdown generated?",
        "text": "The same document IR drives HTML, Markdown and JSON."
      }
    }
  ]
}
```

Renderer HTML (entities decoded and wrapped for display):

```html
<div class="ds-accordion" data-component="accordion" aria-label="FAQ">
<details class="ds-accordion-item" open>
<summary class="ds-accordion-summary">
<span class="ds-accordion-marker" aria-hidden="true" data-markdown-ignore="true">▸</span>How is Markdown generated?</summary>
<div class="ds-prose">The same document IR drives HTML, Markdown and JSON.</div>
</details>
</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/accordion.md`.

### Contract

Packaged: this block ships as `@docsloth/accordion@1.0.0` — an installable component package (kind `block`, capability `render.html`, Apache-2.0) whose production props schema is `packages/contracts/component-props/accordion.schema.json` and whose catalog entry is in `packages/contracts/component-catalog.json`. No protocol manifest fixture is published (`manifest_fixture: null`): the fixture models a packaged protocol runtime this block does not have.

### Intended behavior

Progressive disclosure built on `<details>`/`<summary>`: every child becomes an item whose `label`/`title`/`summary` is the summary text. All panel content stays in the HTML so no-JS and agent readers see it; Markdown flattens to titled `###` subsections with the content directly below.

### Failure and fallback

A child without a label/summary degrades the whole block to the labelled fallback block rather than rendering an unlabelled disclosure; empty children and non-array `children` values do the same. No prop shape throws.

### Required acceptance cases

Assert `details`/`summary` semantics, the first item open by default, the disclosure marker marked `data-markdown-ignore` + `aria-hidden`, `###` heading flattening in Markdown and HTML/Markdown visible-text parity. Also test empty data, a child without a summary, unknown extra props, 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

Block type: `accordion`. Renderer: `packages/renderer/src/index.ts` (native, no permission surface).

#### Native block props

| prop | type | required | behaviour |
| --- | --- | --- | --- |
| `title` | string | no | Optional `aria-label` on the accordion container. |
| `open` | integer | no | Zero-based index of the item open by default (default `0`); out-of-range values simply leave the first item open. |
| `children` | DocBlock[] | yes | One disclosure per child; each child needs a non-empty `label`/`title`/`summary`. |
| `children[].props.open` | boolean | no | `true` forces that item open regardless of `open`. |

#### Example

```json
{
  "type": "accordion",
  "props": { "title": "FAQ" },
  "children": [
    {
      "type": "prose",
      "props": {
        "label": "How is Markdown generated?",
        "text": "The same document IR drives HTML, Markdown and JSON."
      }
    }
  ]
}
```

Markdown:

```markdown
### How is Markdown generated?

The same document IR drives HTML, Markdown and JSON.
```

## Package manifest

No protocol fixture is published for this renderer-native block.

| Field | Value |
| --- | --- |
| Fixture | none published |

## Sources

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