Use
bq-accordion-group to wrap multiple bq-accordion items when you need to coordinate their behavior — for example, collapsing one when another opens.At a glance
- Best for: FAQs, advanced settings, grouped secondary information, and long pages where not every section needs to stay open.
- Use with care: If people need to compare sections side by side or keep several sections visible while working, an accordion may add friction.
- Related components: Use tabs when content belongs to a small set of peer views, or a simple show/hide pattern when only one section needs to expand.
When to use
Use accordions when
- Related content can be grouped into clearly labeled sections
- Page length or visual density needs to be reduced without removing content
- People benefit from scanning headings before deciding what to open
Do not use accordions when
- People need to compare content across sections at the same time
- The content is short enough to show fully without harming readability
- Most sections are likely to be opened during the same task
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Container | The outer wrapper for the entire accordion item |
| 2 | Header | The clickable trigger that toggles the panel open/closed |
| 3 | Panel | The collapsible area containing the body content |
| 4 | Prefix | An optional suffix like an icon or avatar before the header text for additional context |
| 5 | Suffix | An optional prefix for additional context after the header text (less common than prefix) |
| 6 | Expand/Collapse | Icon indicating the current state of the panel and providing a visual affordance for interactivity |
Design guidelines
Use accordions to reduce page density without hiding content that people need to complete the task. Keep each header specific, keep panel content focused, and usebq-accordion-group when several accordion items should behave as one coordinated set.
Usage
The examples below cover the most common ways to use accordions in BEEQ. Start with a single accordion item when sections are independent, and use an accordion group when items should behave as one coordinated set.Default (collapsed)
Accordion items are collapsed by default. This works best when the heading alone gives enough context for someone to decide whether opening the section is worth it.Expanded by default
Use theexpanded attribute when a section should start open — for example when the first item contains the most important information or when one section is expected to be reviewed first.
Options
Appearance
Two appearance values are available:- filled: (default) adds a background color to the header for a contained look
- ghost: removes the background for a minimal style that blends with surrounding content.
Size
Accordions support two sizes:medium (default) and small.
The small size uses more compact padding and a smaller border radius, giving it a tighter look.
Use the
small size in dense layouts or sidebars where space is limited.Group
Wrap relatedbq-accordion items inside bq-accordion-group when they should behave as a coordinated set. By default, only one item can stay open at a time. Add the multiple attribute when people may need to keep several sections open while reading or working.
The group also lets you set appearance, size, and no-animation once and have them cascade to all child accordions.
Attributes/Properties set in the group can be overridden by setting them directly on an individual accordion item.
Single open (default group behavior)
Use the default group behavior when the sections are mutually exclusive or when keeping only one panel open helps reduce distraction.Multiple open
Allow multiple sections to stay open when people may need to review, reference, or complete information across several panels at once.Header slots
Use theprefix slot for adding elements like icons or avatars before the header text, and the suffix slot for elements after the text.
These provide additional context to help people scan and understand the sections.
States
Disabled
Usedisabled only when a section is temporarily unavailable. The header will not respond to interaction and the bqOpen / bqClose events will not fire.
Animation
By default, accordions animate the panel open and closed with a smooth height transition. Add theno-animation attribute to disable this and make the panel appear/disappear instantly.
Custom expand/collapse icons
The accordion provides two separate slots —expand and collapse — to replace the default plus/minus icons.
Use expand for the icon shown when the panel is closed and collapse for the icon shown when the panel is open.
Alternatively, combine a single icon in the expand slot with the rotate prop, which rotates the icon 180° when the accordion opens.
When using a single custom icon with
rotate, make sure the icon is designed to be recognizable in both orientations (e.g., a caret or arrow)
and it’s place in the expand slot, as the rotation is applied to that icon when the accordion is expanded.Custom header layout
Sometimes customizations are needed to meet some requirements. For example, having the collapse/expand indicator in front instead of at the end (current position). Developers can rely on the exposed shadow DOM parts of the components to target elements inside it and tweak not only the look & feel but also the layout.In the example below, we define a custom CSS class that targets the header part to reverse the order of the header content and the expand icon, and also applies flexbox styles to space out the header content.
Then, assuming the custom CSS file is imported in the project, we apply the custom class to the accordion to achieve the desired header layout.
Best practices
DoWrite header labels that clearly describe the content inside. People should be able to predict what they will find before opening the section.
Don’tDo not nest accordions inside accordion panels. It creates unclear hierarchy and makes interaction patterns harder to follow.
DoUse
bq-accordion-group when items belong together and their open/close behavior should be coordinated.Don’tDo not hide critical content inside accordions. If the information is essential to the page, it should usually remain visible.
DoConsider
no-animation or a reduced-motion strategy for workflows where motion may distract or overwhelm.Don’tDo not use an accordion when a simpler show/hide pattern or a tab group would communicate the structure more clearly.
DoKeep panel content focused on the promise made by the header so people can scan and decide quickly.
Don’tDo not use vague headers such as “More details” when a specific label would set clearer expectations.
Accessibility
- Keyboard navigation — the header is a focusable button and can be activated with Enter or Space.
- Clear headings — header labels should describe the panel content clearly enough to be understood before expansion.
- ARIA support — the header exposes
aria-expanded, and the panel visibility is reflected for assistive technologies. - Disabled state — disabled accordions are removed from the tab order, so use this state sparingly and explain unavailable content when possible.
- Reduced motion — use
no-animationwhen motion should be minimized, or respect the user’sprefers-reduced-motionsetting.
API reference
bq-accordion properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
appearance | appearance | The appearance style of the accordion | 'filled' | 'ghost' | 'filled' |
disabled | disabled | If true, the accordion header is not interactive | boolean | false |
expanded | expanded | If true, the accordion panel is expanded | boolean | false |
noAnimation | no-animation | If true, disables the open/close animation | boolean | false |
rotate | rotate | If true, the expand icon rotates 180° when expanded instead of swapping | boolean | false |
size | size | The size of the accordion | 'small' | 'medium' | 'medium' |
bq-accordion-group properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
appearance | appearance | Appearance style applied to all child accordions | 'filled' | 'ghost' | 'filled' |
expandAll | expand-all | If true, all child accordions are expanded | boolean | false |
noAnimation | no-animation | If true, disables animation on all child accordions | boolean | false |
multiple | multiple | If true, multiple accordion items can be expanded at the same time | boolean | false |
size | size | Size applied to all child accordions | 'small' | 'medium' | 'medium' |
Events
| Event | Description | Type |
|---|---|---|
bqBlur | Fires when the accordion loses focus | CustomEvent<HTMLBqAccordionElement> |
bqClick | Fires when the accordion header is clicked | CustomEvent<HTMLBqAccordionElement> |
bqFocus | Fires when the accordion gets focus | CustomEvent<HTMLBqAccordionElement> |
bqOpen | Fires when the accordion panel starts to open | CustomEvent<HTMLBqAccordionElement> |
bqAfterOpen | Fires after the open transition has completed | CustomEvent<HTMLBqAccordionElement> |
bqClose | Fires when the accordion panel starts to close | CustomEvent<HTMLBqAccordionElement> |
bqAfterClose | Fires after the close transition has completed | CustomEvent<HTMLBqAccordionElement> |
- In React, prefix events with
on:onBqBlur,onBqClick,onBqFocus,onBqOpen,onBqClose,onBqAfterOpen,onBqAfterClose. - In Angular, use the event binding syntax:
(bqBlur),(bqClick),(bqFocus),(bqOpen),(bqClose), etc. - In Vue, use the
@shorthand:@bq-blur,@bq-click,@bq-focus,@bq-open,@bq-close, etc.
Slots
bq-accordion
| Slot | Description |
|---|---|
| (default) | The panel body content shown when the accordion is expanded |
collapse | Custom icon shown when the accordion is expanded (clicking will collapse) |
expand | Custom icon shown when the accordion is collapsed (clicking will expand) |
header | The accordion header label (the clickable trigger) |
prefix | Content before the header text — icon or avatar |
suffix | Content after the header text — icon or status indicator |
bq-accordion-group
| Slot | Description |
|---|---|
| (default) | One or more bq-accordion elements |
Shadow parts
bq-accordion
| Part | Description |
|---|---|
base | The <details> element wrapping the accordion |
header | The <summary> element — the clickable header |
panel | The <div> containing the panel body content |
prefix | The <div> wrapping the prefix slot content |
suffix | The <div> wrapping the suffix slot content |
text | The <div> wrapping the header text slot content |
bq-accordion-group
| Part | Description |
|---|---|
base | The wrapper <div> for the accordion group |
CSS custom properties
Resources
Use Storybook to test behavior and states interactively, or review the source if you need implementation details.Interactive playground
Explore all accordion configurations in Storybook
Source code
View the component source on GitHub