Pivot Docs

    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-open present → item is expanded
    • pivot-open absent → 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 id generation: 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 the aria-controls and aria-labelledby relationships 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 delegatesFocus

    Related Components


    References


    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.