Skip to main content Home About the Design SystemRoadmap OverviewDesignersDevelopers OverviewColorGridIconographyInteractionsSpacingTypography Overview Global colorBox shadowTypographyBorderOpacitySpaceLengthIconBreakpointsMedia queries All elements Accordion Alert Announcement Audio player Avatar Back to top Badge Blockquote Breadcrumb Button group Button Card Chip Code block Call to action Dialog Disclosure Footer Health index Icon Jump links Menu dropdown Navigation link Navigation (primary) Navigation (secondary) Navigation (vertical) Pagination PopoverPlanned Progress stepper Readtime Scheme toggle Select Site status Skeleton Skip link Spinner Statistic Subnavigation Surface Switch Table Tabs Tag Tile Timestamp Tooltip Video embed OverviewColor PalettesCustomizingDevelopers All PatternsAccordionAlertCall to ActionCardFilterFormLink with iconLogo wallSearch barSticky bannerSticky cardTabsTagTile All Personalization PatternsAnnouncement FundamentalsAccessibility toolsAssistive technologiesCI/CDContentContributorsDesignDevelopmentManual testingResourcesScreen readers Design/code status Release notes Get support

Accordion

OverviewStyleGuidelinesCodeAccessibilityDemos
ImportingUsagerh-accordionrh-accordion-headerrh-accordion-panelImportingUsagerh-accordionrh-accordion-headerrh-accordion-panel

Importing

Add rh-accordion to your page with this import statement:

<script type="module">
  import '@rhds/elements/rh-accordion/rh-accordion.js';
</script>
Copy to Clipboard Wrap lines

To learn more about installing RHDS elements on your site using an import map read our getting started docs.

Lightdom CSS shim

Warning

Lightdom CSS shims are an optional, temporary solution for reducing CLS. Learn more about lightdom CSS shims .

 
<link rel="stylesheet" href="/path/to/rh-accordion/rh-accordion-lightdom-shim.css">

Note

Replace /path/to/ with path to the CSS file, whether local or CDN.

Usage 

<rh-accordion>
  <!-- H2 tags will be removed on upgrade, rh-accordion-header will set the correct heading level internally using the header tag that wraps it -->
  <h2><rh-accordion-header>Item One</rh-accordion-header></h2>
  <rh-accordion-panel>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
  </rh-accordion-panel>
  <h2><rh-accordion-header>Item Two</rh-accordion-header></h2>
  <rh-accordion-panel>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
  </rh-accordion-panel>
  <h2><rh-accordion-header>Item Three</rh-accordion-header></h2>
  <rh-accordion-panel>
    <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
  </rh-accordion-panel>
</rh-accordion>

<link rel="stylesheet" href="../rh-accordion-lightdom-shim.css">

<script type="module">
  import '@rhds/elements/rh-accordion/rh-accordion.js';
</script>
Copy to Clipboard Wrap lines

rh-accordion

Organizes content into expandable panels for scanning and selective disclosure. Must contain paired rh-accordion-header and rh-accordion-panel children. Should have two or more pairs; for a single section use rh-disclosure. Headers use ARIA role="heading" with aria-expanded/aria-controls for screen readers. Supports keyboard navigation: Tab to move focus, Enter or Space to toggle.

Theming

Themable Color palette

This element uses Red Hat design system theming and can be used in themable contexts.

This element is a color palette container and supports all color palettes via the color-palette attribute.

Slots 1

Slot Name Summary Description
[default]

Alternating rh-accordion-header and rh-accordion-panel pairs

Must contain paired rh-accordion-header and rh-accordion-panel elements in alternating order. Each header Must be immediately followed by its corresponding panel. Should contain at least two pairs. Headers provide aria-controls linking to their panel for screen readers.
Note: [default] unnamed slots do not have a slot="name" attribute.

Attributes 4

Attribute DOM Property Description Type Default
accents accents

Position of accent slot content relative to the header title. Defaults to inline. Use bottom when accents are numerous or the title needs more horizontal space.

 
'inline' | 'bottom'
 
unknown
large large

Switches the accordion to large size, increasing font size and padding. Avoid on viewports below 576px; the accordion automatically falls back to small size on mobile breakpoints. Use large for page-level content sections where the accordion is the primary content structure.

 
boolean
 
false
color-palette colorPalette

Color palette for the accordion and its child headers and panels. Must match the surrounding surface color to ensure adequate text contrast. Avoid mixing light and dark palettes within the same page section.

 
'light' | 'lighter' | 'lightest' | 'dark' | 'darker' | 'darkest'
 
unknown
expanded-index expandedIndex

Comma-separated 0-based indexes of initially expanded panels. Defaults to none (all collapsed). Example: expanded-index="0,2" expands the first and third panels.

 
unknown
 
unknown

Methods 7

Method Name Description
hasChanged()
updateAccessibility()

Initialize the accordion by connecting headers and panels with aria controls and labels; set up the default disclosure state if not set by the author; and check the URL for default open
toggle(index: number)

Accepts a 0-based index value (integer) for the set of accordion items to expand or collapse.
expand(index: number, parentAccordion: RhAccordion)

Accepts a 0-based index value (integer) for the set of accordion items to expand. Accepts an optional parent accordion to search for headers and panels.
expandAll()

Expands all accordion items.
collapse(index: number)

Accepts a 0-based index value (integer) for the set of accordion items to collapse.
collapseAll()

Collapses all accordion items.

Events 2

Event Name Description
expand

Fires when a panel expands. Event detail: toggle (RhAccordionHeader), panel (RhAccordionPanel).
collapse

Fires when a panel collapses. Event detail: toggle (RhAccordionHeader), panel (RhAccordionPanel).

CSS Shadow Parts 0

None

CSS Custom Properties 0

None

Design Tokens 8

Token Description Copy
--rh-color-text-primary

Accordion text color
--rh-color-surface-lightest

Primary surface (light theme)
--rh-color-surface-darkest

Primary surface (dark theme)
--rh-color-surface
--rh-font-size-body-text-md

16px font size
--rh-font-size-body-text-lg

18px font size
--rh-color-border-subtle

Top and bottom border on first header

Bottom border between accordion items

Bottom border on expanded panel
--rh-box-shadow-sm

Depth shadow on expanded accordion group

Depth shadow on expanded panel

Small box shadow

rh-accordion-header

Clickable toggle for an accordion panel. Each header controls the visibility of its adjacent rh-accordion-panel sibling. Renders as an accessible button with role="heading" at the appropriate aria-level.

Must be a direct child of rh-accordion. Should contain concise title text (max 65 characters). Avoid writing titles that sound like calls to action.

Supports keyboard activation with Enter or Space. Automatically manages aria-expanded and aria-controls for its associated panel.

Theming

Themable

This element uses Red Hat design system theming and can be used in themable contexts.

Slots 2

Slot Name Summary Description
[default]

panel's title text or heading content

Contains the primary label that describes what content will be revealed when the panel expands. Title text should be written concisely (max 65 characters) so users know what to expect. Avoid writing titles that sound like calls to action - make it easy for users to understand the content within. Title text that is too long should be broken into separate sections, and text that is too vague may not help users understand the panel content.

@see Title text in Guidelines documentation
Note: [default] unnamed slots do not have a slot="name" attribute.
accents

decorations like icons or tags

These elements will appear inline by default with the header title, between the header and the chevron (or after the chevron and header in disclosure mode). There is an option to set the accents placement to bottom

Attributes 1

Attribute DOM Property Description Type Default
expanded expanded

Whether this header's associated panel is expanded. When true, the caret icon rotates upward and the panel content is visible. Managed automatically by the parent rh-accordion — set expanded-index on the accordion to control initial state declaratively.

 
boolean
 
false

Methods 0

None

Events 1

Event Name Description
change

Fires when the header's expanded state changes, either by user click or programmatic toggle. The event expanded property indicates the new state.

CSS Shadow Parts 2

Part Name Summary Description
text

inline element containing the heading text or slotted heading content
accents

container for accents within the header

CSS Custom Properties 0

None

Design Tokens 13

Token Description Copy
--rh-space-lg

16px spacer
--rh-space-xl

24px spacer
--rh-border-width-sm

1px border width; Example: Secondary CTA or Button
--rh-color-border-subtle
--rh-font-family-body-text

Header toggle typeface

Body text font family
--rh-color-surface-lighter

Tertiary surface (light theme)
--rh-color-surface-dark

Tertiary surface (dark theme)
--rh-color-text-primary

Header toggle text color
--rh-color-interactive-primary-default

Focus ring color on header toggle
--rh-border-width-lg

Accent bar thickness

3px border width: Example: Expanded Accordion panel
--rh-color-accent-brand
--rh-font-weight-body-text-medium

Header toggle text weight

Header title text weight

Medium font weight
--rh-space-md

Gap between title and accents

Spacing between accent items

8px spacer

rh-accordion-panel

Collapsible content region within an accordion, paired with an rh-accordion-header. Renders with role="region" and aria-labelledby linking to its header for screen reader context.

Must be a direct child of rh-accordion, immediately following its corresponding rh-accordion-header. Panel content can include text, cards, images, or nested accordions. Text blocks should not exceed 750px width for optimal readability.

Theming

Themable

This element uses Red Hat design system theming and can be used in themable contexts.

Slots 1

Slot Name Summary Description
[default]

The content of the accordion panel can be any basic markup including but not limited to div, paragraph, or nested accordion panels.
Note: [default] unnamed slots do not have a slot="name" attribute.

Attributes 1

Attribute DOM Property Description Type Default
expanded expanded

Sets the initial visibility state of the panel content. When true, the panel is expanded and its content is visible. When false (default), the panel is collapsed and its content is hidden.

Usage guidelines

  • Use to draw attention to important content that should be immediately visible
  • Set on the first panel in a FAQ or help section to show the most common question
  • Supports multiple panels being expanded simultaneously for content comparison
  • Users can expand and collapse panels one at a time by default, or multiple panels when implementing "Expand all" functionality

By default, all panels are collapsed (expanded=false). Users expand panels by clicking the header, which animates the caret icon and reveals the content.

See Expanding and collapsing panels in Guidelines documentation

 
boolean
 
false

Methods 0

None

Events 0

None

CSS Shadow Parts 1

Part Name Summary Description
container

main wrapper region that contains the panel content

The container part represents the structural element that holds the panel's body content. It maintains the color scheme context to ensure proper text visibility and color contrast, and should match the color palette of the container it's in. This part defines the overall styling and boundaries for the panel's revealed content area.

CSS Custom Properties 0

None

Design Tokens 7

Token Description Copy
--rh-space-xl

24px spacer
--rh-space-md

8px spacer
--rh-space-lg

16px spacer
--rh-color-border-subtle

Panel trailing border
--rh-border-width-lg

Accent bar thickness

3px border width: Example: Expanded Accordion panel
--rh-color-accent-brand

Expanded panel accent bar color
--rh-color-text-primary

Panel content text color
Edit this page on GitHub
© 2026 Red Hat Deploys by Netlify