Accordion Item
pivot-accordion-item is a disclosure web component that shows or hides a section of content. It is designed to be used as a direct child of pivot-accordion-default or pivot-accordion-elevated.
Quick Start
<pivot-accordion-default>
<pivot-accordion-item pivot-item-label="Getting Started">
<p>Place any content here — text, lists, forms, or other components.</p>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Advanced Configuration">
<p>Content for the second section.</p>
</pivot-accordion-item>
</pivot-accordion-default>To start an item in the expanded state, include the pivot-open attribute:
<pivot-accordion-item pivot-item-label="Expanded by Default" pivot-open>
<p>This item is already expanded on page load.</p>
</pivot-accordion-item>Using the pivot-accordion-item-toggle event
Fired on every toggle, whether opening or closing. The event bubbles and is composed, so it crosses shadow DOM boundaries and can be caught from a listener on pivot-accordion-default or pivot-accordion-elevated.
document
.querySelector("pivot-accordion-default")
.addEventListener("pivot-accordion-item-toggle", (e) => {
console.log("Label:", e.detail.label);
console.log("Now open:", e.detail.pivotOpen);
});Detail shape:
{
pivotOpen: boolean; // true when the item was just opened, false when closed
label: string; // the pivot-item-label value of the toggled item
}Note that this event fires from user interaction with the header button only (click, Enter, or Space) — setting the pivot-open attribute or pivotOpen property programmatically does not dispatch it.
Behavior
Expand and Collapse
Clicking anywhere in the header button area toggles the item open or closed. Content expands and collapses using a CSS grid row animation (grid-template-rows: 0fr → 1fr), which avoids JavaScript-driven height measurement. Collapsed content stays in the DOM, so it remains available to search engine crawlers.
While collapsed, the panel is also set to visibility: hidden, which removes its content from the accessibility tree and the Tab order. Visibility transitions with the height animation, so content stays visible until the panel finishes closing and appears as soon as it starts opening.
The pivot-open attribute reflects the current state and is used as a CSS selector hook:
pivot-openpresent → item is expandedpivot-openabsent → item is collapsed
The pivotOpen property reflects to the pivot-open attribute, so setting either one — or toggling the item through the header button — keeps both in sync and drives the attribute-based CSS styling.
Elevated Surface
When used inside pivot-accordion-elevated, the container sets pivot-surface="elevated" on each child item. pivot-surface is parent-managed and should not be set directly on pivot-accordion-item in normal usage. In elevated mode, each item receives card styling:
- Rounded corners on the container
- Box shadow when expanded
- Bottom margin when expanded, to separate from adjacent items
- Transparent header border when expanded
pivot-accordion-elevated also enforces single-open behavior for items opened through their header button: only one item can be open at a time. See the Accordion Elevated README for how this interacts with opening items from script.
Adjacent Border Management
Inside pivot-accordion-elevated, the bottom border of an item is hidden when the immediately following sibling is open. This prevents a visual double-border between adjacent elevated items.
The border transitions back in when the following item collapses. This state is managed via the pivot-next-open attribute, which pivot-accordion-elevated sets and removes automatically — including on initial render for items with pivot-open in the markup. It should not be set manually.
Motion and Reduced Motion
The expand/collapse animation and chevron rotation both use CSS transitions. Under prefers-reduced-motion: reduce, all transitions are disabled and states change instantly.
Accessibility
pivot-accordion-item conforms to the ARIA Accordion Pattern.
ARIA Roles and Attributes
| Element | Role / Attribute | Value | Purpose |
|---|---|---|---|
Header wrapper <div> |
No implicit heading semantics | — | Groups the header button visually and structurally |
<button> |
aria-expanded |
"true" / "false" |
Communicates the expanded or collapsed state to assistive technology |
<button> |
aria-controls |
"accordion-content-{nanoid}" |
Associates the button with the panel it controls |
Panel <div> |
role="region" |
— | Creates an accessible landmark region for the panel content |
Panel <div> |
aria-labelledby |
"accordion-label-{nanoid}" |
Associates the region with its header button for an accessible name |
Panel <div> |
hidden |
boolean | Hides collapsed content from all users, including screen reader users |
Note on
idgeneration: The item wrapper, button, and panel each get a single unique ID (accordion-item-{nanoid},accordion-label-{nanoid},accordion-content-{nanoid}) generated once per instance. These IDs stay stable across re-renders, so thearia-controlsandaria-labelledbyrelationships never point at a stale ID. The IDs live in the shadow DOM and are not configurable.
Screen Reader Behavior
When focus moves to an accordion header button, screen readers announce:
- The label text (e.g., “Getting Started”)
- The element role: “button”
- The expanded state: “expanded” or “collapsed”
When the user activates the button, the updated state is announced and the panel content (when expanded) becomes available in the reading flow via the role="region" landmark.
The chevron icon is decorative SVG and carries no accessible text. The expanded/collapsed state is communicated entirely through aria-expanded on the button.
Keyboard Navigation
These interactions follow the ARIA APG Accordion example:
| Key | Action |
|---|---|
Tab |
Moves focus to the next focusable element (next accordion header, or interactive content within an open panel) |
Shift + Tab |
Moves focus to the previous focusable element |
Enter or Space |
Toggles the focused accordion item open or closed |
ArrowDown |
Moves focus to the next accordion header in the group (wraps to first) |
ArrowUp |
Moves focus to the previous accordion header in the group (wraps to last) |
Home |
Moves focus to the first accordion header in the group |
End |
Moves focus to the last accordion header in the group |
Arrow key navigation works by querying the parent element for all sibling pivot-accordion-item elements. Items must share a common parent (either pivot-accordion-default or pivot-accordion-elevated) for arrow key traversal to function correctly.
Focus Management
The component inherits delegatesFocus: true from PivotBase. This means:
- Focus on the host element (
pivot-accordion-item) automatically delegates to the internal header button - Programmatic
.focus()on the element will land on the button
To programmatically focus an item:
const item = document.querySelector("pivot-accordion-item");
item.focus(); // Delegates to the internal button via delegatesFocusRelated Components
- Accordion Default — list-styled container where multiple items can be open at once.
- Accordion Elevated — card-styled container with single-open behavior and an optional numbered type.
- Accordion Stand Alone — single disclosure used on its own, without a container.
References
- ARIA Authoring Practices Guide — Accordion Pattern
- ARIA Authoring Practices Guide — Accordion Example
- Carbon Design System — Accordion Accessibility
- Carbon Design System — Accordion Usage
- WCAG 2.2 — 4.1.2 Name, Role, Value
API Reference
Props
| Name | Type | Default | Description |
|---|---|---|---|
pivot-item-label |
string |
"" |
The label text displayed in the accordion label. |
pivot-open |
boolean |
false |
Controls whether the accordion item is expanded or collapsed. |
pivot-step |
number | null |
null |
Step number shown before the label. Set automatically by a parent accordion with `pivot-type="numbered"`. |
Slots
| Name | Description |
|---|---|
default |
Content displayed inside the expanded accordion panel |
Events
| Name | Type | Description |
|---|---|---|
pivot-accordion-item-toggle |
CustomEvent |
Fired when the item is expanded or collapsed. Detail: `{ pivotOpen: boolean, label: string }` |
CSS Custom Properties
| Name | Description |
|---|---|
--component-accordion-list-gap |
Gap between the label and chevron in the list variant button. |
--component-accordion-list-inset-y |
Vertical padding of the header button. |
--component-accordion-list-inset-x |
Horizontal padding of the header button, and of the panel content while collapsed. |
--component-accordion-elevated-gap |
Gap between the step number, label, and chevron in the elevated and numbered variants. |
--component-accordion-elevated-inset-y |
Vertical padding of the panel content while expanded, and bottom margin of an expanded elevated item. |
--component-accordion-elevated-inset-x |
Horizontal padding of the panel content while expanded. |
--component-divider-default |
Color of the item's bottom border. |
--typography-constants-headline-family |
Font family of the label. |
--typography-headline-sm-size |
Font size of the label. |
--typography-headline-sm-height |
Line height of the label. |
--global-color-text-on-light-dark-color |
Text color of the label. |
--global-color-icons-font-awesome-default-color |
Color of the chevron icon. |
--component-accordion-elevated-numbered-inset |
Padding inside the step number badge. |
--component-accordion-elevated-numbered-border |
Border width of the step number badge. |
--component-accordion-elevated-numbered-radius |
Border radius of the step number badge. |
--typography-private-callout-family |
Font family of the step number. |
--typography-private-accordion-elevated-number-size |
Font size of the step number. |
--typography-private-accordion-elevated-number-height |
Line height of the step number. |
--component-accordion-elevated-numbered-label-deselected |
Step number color while collapsed. |
--component-accordion-elevated-numbered-surface-deselected |
Step number badge background while collapsed. |
--component-accordion-elevated-numbered-border-deselected |
Step number badge border color while collapsed. |
--component-accordion-elevated-numbered-label-selected |
Step number color while expanded. |
--component-accordion-elevated-numbered-surface-selected |
Step number badge background while expanded. |
--component-accordion-elevated-numbered-border-selected |
Step number badge border color while expanded. |
--global-radius-md |
Corner radius of an elevated item. |
--global-elevation-shadow1-x |
Horizontal offset of an expanded elevated item's shadow. |
--global-elevation-shadow1-y |
Vertical offset of an expanded elevated item's shadow. |
--global-elevation-shadow1-blur |
Blur radius of an expanded elevated item's shadow. |
--global-elevation-shadow1-spread |
Spread radius of an expanded elevated item's shadow. |
--global-elevation-shadow1-fill |
Color of an expanded elevated item's shadow. |
Closed and open (pivot-open)
Each item can independently start open via pivot-open. See the Accordion examples for how multiple items behave together inside a full pivot-accordion-default. For a single isolated disclosure, use pivot-accordion-stand-alone.
<pivot-accordion-default>
<pivot-accordion-item pivot-item-label="List item (closed)">
<pivot-text>List-type content, collapsed by default.</pivot-text>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="List item (open)" pivot-open>
<pivot-text>List-type content, expanded by default.</pivot-text>
</pivot-accordion-item>
</pivot-accordion-default>Elevated surface and adjacent border management (pivot-surface, pivot-next-open)
pivot-surface="elevated" is set by the parent pivot-accordion-elevated on each child item, giving every item card styling — rounded corners, a box shadow, and a bottom margin while it’s expanded. When an item opens, pivot-accordion-elevated also sets pivot-next-open on the item immediately above it, which transparently hides that item’s bottom border so two adjacent elevated items never show a doubled line. Both pivot-surface and pivot-next-open are parent-managed and should not be set on pivot-accordion-item directly.
<pivot-accordion-elevated>
<pivot-accordion-item pivot-item-label="Section 1 (closed)">
<pivot-text
>Section 2 below is open, so this item's bottom border is hidden via
pivot-next-open.</pivot-text
>
</pivot-accordion-item>
<pivot-accordion-item pivot-item-label="Section 2 (open)" pivot-open>
<pivot-text
>This item shows the elevated card styling: rounded corners, drop shadow,
and bottom margin.</pivot-text
>
</pivot-accordion-item>
</pivot-accordion-elevated>