# ExpandableSection

> Collapsible content region with a trigger header. Lighter than `Accordion` (which manages a group of expandables); used standalone for a single 'show more' or detail-disclosure section.

- Status: stable
- Group: structure
- Page: https://www.digitaltableteur.com/design-system/components/expandable-section
- Contract: https://www.digitaltableteur.com/contracts/v1/ExpandableSection.contract.json

## When to use

ExpandableSection is a single, independent disclosure: one trigger whose label can swap between states (`collapsedLabel`/`expandedLabel`), revealing its children with a height and fade transition while the content slides up slightly. Use it for "show more" tails: extended bios, optional details, long changelogs. It has no group behavior: several ExpandableSections don't know about each other. When sections should be exclusive (open one, close the other), that is Accordion.

## When not to use

- Do not use a sequence of `ExpandableSection`s instead of `Accordion`; accordion owns the focus management and single-open behaviour.
- Do not hide critical content (errors, primary CTA) behind a disclosure.

## Look-alikes

- Accordion: Do not build exclusive groups from several ExpandableSections; that is Accordion's contract.

## Props

| Prop | Type | Default | Description | Required |
| --- | --- | --- | --- | --- |
| `collapsedLabel` | `string` | none | Trigger label when collapsed. | Yes |
| `expandedLabel` | `string` | none | Trigger label when expanded (optional, defaults to collapsedLabel) | No |
| `defaultExpanded` | `boolean` | `false` | Whether the section is initially expanded. | No |
| `expanded` | `boolean` | none | Controlled expanded state. | No |
| `onExpandedChange` | `(expanded: boolean) => void` | none | Callback when expansion state changes. | No |
| `children` | `ReactNode` | none | Content to reveal. | Yes |
| `className` | `string` | none | Additional className for the container. | No |

## Variants

No variant dimensions and no props with a fixed set of values.

## Invalid combinations

- MUST NOT: `expanded` and `defaultExpanded` set together. `expanded` makes the component controlled and `defaultExpanded` uncontrolled; pass one, not both.

## Keyboard

| Key | Behaviour |
| --- | --- |
| Tab | Focuses the trigger header. |
| Enter / Space | Toggles the section. |

## Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

| Level | Rule | How it is checked |
| --- | --- | --- |
| MUST NOT | `expanded` and `defaultExpanded` set together. `expanded` makes the component controlled and `defaultExpanded` uncontrolled; pass one, not both. | Checked by the MCP tool validate_component_usage. |
| MUST | ARIA: Trigger is a `<button>` with `aria-expanded` reflecting the open state. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | ARIA: The panel is added/removed on toggle (no dangling `aria-controls`); the trigger's text label is its accessible name. | Not yet verified: no evidence record. WCAG 4.1.2. |
| MUST | Required stories produce no axe violations at the configured severity. | Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8. |
| MUST | The accessibility tree (role, name, state) matches the committed snapshot for every required story. | Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2. |
| MUST | The component remains legible and operable under a real browser forced-colors: active pass. | Automated by `npm run test:stories:hc`. |
| MUST | Positional, scale, and opacity motion is suppressed under prefers-reduced-motion. | Manual review, last on 2026-11-04. WCAG 2.2.2, 2.3.3. |
| MUST | Every documented keyboard interaction works as specified. | Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2. |
| MUST | A human completed an end-to-end accessibility review of this component. | Manual review, last on 2026-11-04. |
| SHOULD | Give expandedLabel the inverse verb ("Show less") so the trigger always states what it will do. | Not stated in the contract. |
| SHOULD | Use it for optional tails of content, not for the content's opening. | Not stated in the contract. |
| SHOULD | Use controlled mode (expanded + onExpandedChange) when analytics or URL state care about the disclosure. | Not stated in the contract. |
| SHOULD | Keep the reveal short; dozens of children behind one disclosure read as lag; split long lists instead. | Not stated in the contract. |
| SHOULD NOT | Do not build exclusive groups from several ExpandableSections; that is Accordion's contract. | Not stated in the contract. |
| SHOULD NOT | Do not hide required form fields inside; validation errors in collapsed content are invisible. | Not stated in the contract. |

## Install and import

- Install: `npm install @digitaltableteur/react` (version 0.9.1, restricted access on npm).
- Import: `import { ExpandableSection } from "@digitaltableteur/react";`
- Entry point: `@digitaltableteur/react/content` exports it too.
- Styles: import `@digitaltableteur/react/style.css` once at the app boundary.
- Also available as the custom element `<dt-expandable-section>`; see the custom elements manifest.

## Links

- Machine-readable contract (Design System Contract 1.0): https://www.digitaltableteur.com/contracts/v1/ExpandableSection.contract.json
- Markdown version of this page: https://www.digitaltableteur.com/design-system/components/expandable-section.md
- Component index as JSON: https://www.digitaltableteur.com/design-system/components.json
- All components: https://www.digitaltableteur.com/design-system/components
- Source: The implementation lives in a private repository. This page, its Markdown twin and the contract are generated from it at build time and are the public source of truth.