What is the Bootstrap accordion?
Each panel is a header with a block of content under it, and clicking the header expands or collapses that block. It ships with Bootstrap as one of the framework’s ready-made components, and all of its behavior comes from the Collapse plugin. The Bootstrap 5.3 documentation frames it as a vertical accordion layer on top of that plugin.
The .collapse class hides a panel and .collapse.show displays it. A third class, .collapsing, sits on the panel only while the height transition runs. On a click, the plugin animates the height between 0 and the full size and flips aria-expanded on the trigger.
The animation follows the prefers-reduced-motion media query, so visitors who set that preference in their system don’t get it.
It isn’t a tab set, though people mix the two up. Tabs built with Bootstrap’s tab component always keep one pane active, while an accordion can sit with every panel closed.
Everything here reflects Bootstrap 5.3.8, the latest stable release as of October 2026. Bootstrap 6 entered alpha on October 8, 2026 and builds its accordion on native details and summary elements, so it isn’t covered.
How to build a Bootstrap accordion
The page needs Bootstrap’s CSS and JavaScript bundle first. After that it’s five nested classes per item, plus matching ids between each button and its panel.
Files to load
The stylesheet goes in the head and the script goes before the closing body tag. The Bootstrap 5.3 docs give jsDelivr links for both, and the bootstrap package installs from npm if you build with a bundler.
bootstrap.bundle.min.js includes Popper. bootstrap.min.js alone also works, since the accordion doesn’t use Popper. Whichever you pick, update the integrity hash whenever the version changes.
Because the accordion is plain HTML plus data attributes, no initialization script is needed.
Accordion markup
- Wrap the panels in a div with the class accordion and a unique id, such as accordionExample.
- Add one div with the class accordion-item for each panel.
- Inside it, place an h2 with the class accordion-header that wraps a button with the class accordion-button, type=”button”, data-bs-toggle=”collapse” and a data-bs-target pointing at the panel id.
- Add a div with the classes accordion-collapse and collapse, carrying that same id.
- Put the content in a div with the class accordion-body inside the panel.
<div class="accordion" id="accordionExample">
<div class="accordion-item">
<h2 class="accordion-header">
<button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#collapseOne" aria-expanded="false" aria-controls="collapseOne">
Item one
</button>
</h2>
<div id="collapseOne" class="accordion-collapse collapse" data-bs-parent="#accordionExample">
<div class="accordion-body">Panel content.</div>
</div>
</div>
</div>
Repeat the accordion-item block for every extra panel, with a new id each time.
How the ids connect
One mismatched id breaks an item, and nothing on the page tells you why.
data-bs-target holds a CSS selector, usually #collapseOne. aria-controls repeats the panel id without the hash, and the id itself has to be unique on the page. Bootstrap looks elements up with querySelector, so ids containing special characters need escaping (Bootstrap 5.3 documentation).
The example wraps each button in an h2. Change the tag to whatever level fits your page outline, since the classes handle the styling, not the element.
Open state: one panel, many panels, or open by default
Whether panels open one at a time or independently comes down to data-bs-parent. The show class and the button’s aria-expanded value decide what is open on load.
| Setup | data-bs-parent | Starting markup | Behavior |
|---|
| Single open | On every .accordion-collapse | .show on one panel | Opening a panel closes the open one |
| Always open | Omitted everywhere | .show on any number of panels | Panels open and close independently |
| All closed | Either | No .show, .collapsed on every button | Nothing is open on load |
Keep one panel open at a time
Set data-bs-parent="#accordionExample" on every .accordion-collapse element, using the id of the .accordion container. The Collapse docs place the attribute on the collapsible area, never on the button.
Clicking the header of the open panel still closes it. So this setup caps the accordion at one open panel but doesn’t guarantee one is always visible.
Always-open accordion
Remove data-bs-parent from every .accordion-collapse. That’s the entire change.
Panels then behave independently, which suits FAQ lists where visitors compare two or three answers side by side.
Open a panel by default
Add show to the accordion-collapse element. On the button, remove collapsed and set aria-expanded=”true”.
Skip any of those and either the chevron or the announced state is wrong until the first click.
Controlling the Bootstrap accordion with JavaScript
The accordion opens and closes without any custom script, so code only becomes necessary when you want to drive panels programmatically or react to state changes. The Collapse class behind it exposes 6 methods, 2 options and 4 events (Bootstrap 5.3 documentation).
It all runs on vanilla JavaScript, because Bootstrap 5 dropped the jQuery dependency (Bootstrap migration guide).
Initialize and configure
Manual setup loops over the .collapse elements inside the accordion and creates one instance per panel.
const items = document.querySelectorAll('#accordionExample .collapse')
items.forEach(el => new bootstrap.Collapse(el, { toggle: false }))
The toggle option defaults to true and toggles the panel on invocation, so creating instances in a loop flips each panel unless you pass toggle: false. The snippet in the accordion docs leaves that option out.
The other option is parent, which takes a selector or DOM element and defaults to null. When a panel opens, any sibling panels under that parent close. toggle is a plain boolean.
Methods and the transition rule
Use show, hide and toggle to open and close panels, and getOrCreateInstance to fetch an instance without checking whether one exists. All of them belong to Bootstrap’s programmatic API and return before the transition ends.
A call on a panel that is still animating is ignored. Wait for the shown or hidden event before chaining the next action.
Here’s how to collapse every open panel:
document.querySelectorAll('#accordionExample .collapse.show').forEach(el => {
bootstrap.Collapse.getOrCreateInstance(el, { toggle: false }).hide()
})
Events
show.bs.collapse fires as soon as show is called, and shown.bs.collapse fires after the transition finishes. The hide side works the same way. hide.bs.collapse fires on the call, and hidden.bs.collapse fires once the panel is fully hidden.
Attach listeners to the .accordion-collapse element, not to the button.
The show and hide events accept preventDefault(), so a handler can veto opening a panel.
There’s one trap. When jQuery is on the page and body has no data-bs-no-jquery attribute, Bootstrap emits its events through jQuery’s event system. The docs then tell developers to listen with .on or .one instead of addEventListener.
Styling the Bootstrap accordion: flush variant, CSS variables and Sass
Styling happens in layers. Sass variables set the build-time defaults, and CSS variables on .accordion override them at runtime. On top of both there’s .accordion-flush for an edge-to-edge layout.
Component CSS variables arrived in Bootstrap 5.2.0 (Bootstrap blog, July 19, 2022). The 5.3.8 docs list 21 of them for the accordion.
Flush variant
Add .accordion-flush to the .accordion container. It strips some borders and rounded corners so the accordion sits edge to edge inside its parent.
It works well inside a card, a sidebar or any bordered wrapper. On a bare page background a flush accordion looks unfinished, at least to me.
CSS variables
–bs-accordion-bg sets the panel background, –bs-accordion-active-bg sets the background of the open button, and –bs-accordion-active-color sets its text color. The focus ring comes from –bs-accordion-btn-focus-box-shadow.
.accordion-brand {
--bs-accordion-active-bg: #fff3cd;
--bs-accordion-active-color: #664d03;
}
The variables are declared on .accordion, so a rule in a stylesheet loaded after Bootstrap’s CSS wins. That’s the standard route for overriding Bootstrap’s default styles without touching the source.
Sass variables
Sass sets the defaults the CSS variables inherit. Most spacing changes come down to $accordion-padding-y (1rem), $accordion-padding-x (1.25rem) and $accordion-icon-width (1.25rem).
Overrides go after @import “functions” and before @import “variables”, because a default cannot be changed once it has been used (Bootstrap 5.2.0 migration notes).
Chevron icon and animation speed
The chevron is an SVG data URI assigned through $accordion-button-icon and exposed as –bs-accordion-btn-icon and –bs-accordion-btn-active-icon. Open panels rotate it by -180 degrees with a .2s transform transition.
To swap in a plus and minus pair, set both icon variables and set –bs-accordion-btn-icon-transform to none, or the new icon rotates too. The icons that ship with Bootstrap work as a source for the SVG files.
The panel height animation is separate. It comes from $transition-collapse, which defaults to height .35s ease and is shared by the Collapse plugin and the accordion, so changing it affects both (Bootstrap 5.3 documentation).
Padding cannot go on a .collapse element because it breaks the height animation. Put it on .accordion-body instead.
Is the Bootstrap accordion accessible?
Mostly, yes. The default markup follows the structure of the W3C ARIA Authoring Practices Guide accordion pattern, and keyboard support comes from a native button. What’s left is a few optional pieces, plus whatever your own content and colors add.
What Bootstrap handles
Each header is a heading wrapping a single button, which is the arrangement the guide asks for. Enter and Space toggle a panel, and Tab and Shift+Tab move between headers.
The header button also carries the ARIA states the guide requires, aria-expanded for visibility and aria-controls for the panel id.
One optional piece is missing from the 5.3 example, role=”region” with aria-labelledby on each panel. The guide advises against region roles in an accordion with more than approximately 6 panels that can be expanded at the same time (W3C, ARIA Authoring Practices Guide).
The Bootstrap 4.6 docs example puts aria-labelledby on every panel, while the 5.3 example leaves it out. Tutorials that include it follow the older pattern, and the guide treats the attribute as optional.
Colors are on you. Bootstrap’s accessibility docs warn that some default palette combinations fall below the WCAG 2.2 minimum of 4.5:1, so check the contrast between text and background for any active-state colors you set.
Closing the keyboard gap
The current ARIA Authoring Practices Guide accordion page lists Enter or Space, Tab and Shift+Tab as its keyboard interactions, and a native button already covers all of them.
Bootstrap’s Collapse docs still say the implementation skips the guide’s optional keyboard interactions, a note the 4.6 docs carry in slightly different words.
Read together, the two sources say arrow-key movement between headers is a nicety, not a failure of the pattern. Add it when an accordion has many items.
document.querySelectorAll('.accordion').forEach(accordion => {
accordion.addEventListener('keydown', event => {
const buttons = [...accordion.querySelectorAll('.accordion-button')]
const index = buttons.indexOf(document.activeElement)
if (index === -1) return
const moves = { ArrowDown: index + 1, ArrowUp: index - 1, Home: 0, End: buttons.length - 1 }
if (!(event.key in moves)) return
event.preventDefault()
buttons[(moves[event.key] + buttons.length) % buttons.length].focus()
})
})
Nested accordions need a narrower selector, otherwise inner headers join the outer list.
Bootstrap 4 vs Bootstrap 5 accordion
In Bootstrap 4 the accordion is built from cards and driven by jQuery. Bootstrap 5 gives you a dedicated .accordion component with data-bs-* attributes, and the migration guide lists it as a v5.0.0 change that replaces the card-based version.
| Aspect | Bootstrap 4.6 | Bootstrap 5.3 |
|---|
| Panel markup | .card with .card-header and .card-body | .accordion-item with .accordion-header and .accordion-body |
| Trigger | button.btn-link with data-toggle and data-target | button.accordion-button with data-bs-toggle and data-bs-target |
| Grouping | data-parent | data-bs-parent |
| Plugin call | $(‘.collapse’).collapse() | new bootstrap.Collapse(el) |
The four collapse event names carried over unchanged, so only the way you subscribe to them differs.
When migrating, the attribute renames are simple:
- data-toggle becomes data-bs-toggle
- data-target becomes data-bs-target
- data-parent becomes data-bs-parent
The migration guide describes the change as namespacing every plugin’s data attributes under data-bs-. The card classes have no automatic replacement, so the panel markup gets rewritten by hand.
Mixed attributes break the accordion in both directions. A Liferay DXP 7.3 forum thread had Bootstrap 5 attributes on a page running an older Bootstrap, and Liferay’s own support notes say its DXP 7.4 platform supports Bootstrap 4, where data-bs-toggle and data-bs-target do nothing.
A Wappler community thread shows the reverse. A project switched to Bootstrap 5 while a trigger still carried data-target next to data-bs-toggle, and the accordion cards would not expand.
The docs disagree with themselves on one point. Both the 4.6 and 5.3 Collapse option tables tie the parent option to the card class, yet the 5.3 accordion example groups .accordion-item panels with data-bs-parent and no card. Follow the example markup, not the option description.
Bootstrap 4 has reached end of life according to the banner on its own 4.6 docs, so a new accordion belongs on Bootstrap 5. Keep the card markup only where the rest of the site still runs 4.6.
Why is the Bootstrap accordion not working?
Most failures come from mismatched attribute prefixes, a missing data-bs-parent target, nested groups, framework conflicts, or content clipped during the animation.
| Symptom | Cause | Fix |
|---|
| Nothing toggles, no error | data-toggle on Bootstrap 5, or data-bs-toggle on Bootstrap 4 | Match every attribute to the loaded version |
| TypeError about querySelectorAll of null (Bootstrap 4.x) | data-parent points to an id missing from the DOM, or util.js is not loaded before collapse.js in a custom build | Point to an existing id, or include util.js first |
| Nested panels do not close each other | Inner group sits inside an outer panel that has .collapse (a 5.1.0 and 5.1.1 regression) | Update to 5.1.2 or later, or close siblings in a show.bs.collapse handler |
| Stuck or inconsistent panels in React, Vue or Angular | Bootstrap JavaScript and the framework both mutate the same DOM elements | Use a framework package such as React Bootstrap or ng-bootstrap |
| Content looks clipped mid-animation | The transition limits overflow while .collapsing is applied | Judge the layout after shown.bs.collapse fires |
The two Bootstrap 4 causes come from twbs/bootstrap issue 26891, where a maintainer traced the error to a missing parent id and another commenter fixed it by loading util.js first. The framework row comes straight from the Bootstrap 5.3 JavaScript docs, which recommend framework-specific packages instead of Bootstrap’s own scripts.
How to nest an accordion without breaking grouping
Place the inner accordion inside an .accordion-body, since the docs allow almost any HTML there. Give the inner container its own id and point the inner panels’ data-bs-parent at it.
Issue 34850 in the twbs/bootstrap repository reported that on Bootstrap 5.1 the inner panels stopped closing each other when the outer panel carried the .collapse class. One reporter’s demo showed the same markup grouping correctly on 4.6.
The cause was a selector missing :scope, and the fix (pull request 34951) shipped in Bootstrap 5.1.2 in October 2021, so nested groups work with plain data-bs-parent on 5.3.8. Only a site stuck on 5.1.0 or 5.1.1 needs a handler that skips data-bs-parent on the inner panels:
document.querySelectorAll('#innerAccordion .collapse').forEach(panel => {
panel.addEventListener('show.bs.collapse', event => {
event.stopPropagation()
document.querySelectorAll('#innerAccordion .collapse.show').forEach(open => {
if (open !== panel) {
bootstrap.Collapse.getOrCreateInstance(open, { toggle: false }).hide()
}
})
})
})
Events bubble, which is why stopPropagation sits in the handler. A commenter on the same thread hit the reverse symptom on 5.0.1, where clicks inside an accordion closed the hamburger menu around it until they stopped the propagation.
Bootstrap accordion or the native details element?
If the page already loads Bootstrap’s JavaScript and you need Collapse events or code-driven control, the Bootstrap accordion makes sense. Otherwise details and summary is enough, because the browser handles the toggling with no script.
The Bootstrap version earns its place when you need show, hide, shown or hidden events, when panels open or close from code, or when the styling has to match the rest of a Bootstrap site.
Details and summary fits when the page doesn’t load Bootstrap JavaScript, or when content must stay readable with scripts disabled. It also works if one open panel at a time is all the grouping you need and a single toggle event is enough.
Bootstrap’s docs state that its plugins have no special fallback when JavaScript is disabled, and panels without the show class stay hidden through CSS. A details element opens and closes without any script.
Exclusive grouping needs only a shared name attribute on each details element. MDN lists the element as available across browsers since January 2020, and the name attribute reached Baseline Newly available on September 3, 2024 (Chrome 120 and Safari 17.2 in December 2023, Firefox 130 in September 2024, per Web Platform DX feature data).
Animation used to be the argument for the Bootstrap accordion. MDN now documents the ::details-content pseudo-element for animating the open and close transition, which narrows that gap.
Sources split on single-open behavior. The ARIA Authoring Practices Guide describes implementations that allow only one expanded panel, while Builder.io’s guide to animated CSS accordions warns that exclusive accordions carry accessibility and UX tradeoffs.
The data-bs-parent setup and the name attribute share that tradeoff, so the choice between them does not settle it.
Neither option fits content visitors need on every visit. Hiding answers behind clicks costs usability for anyone who needs every answer, so keep that content visible.
Bootstrap accordion FAQ
How do I open a specific item from the URL hash?
Bootstrap has no built-in hash handling, so a short script does it. On page load, read location.hash, find the matching .accordion-collapse element, and call getOrCreateInstance(element, { toggle: false }).show().
Give each panel an id that matches the hash you link to.
Can the trigger be a link instead of a button?
Yes. Use an a element with data-bs-toggle=”collapse”, an href pointing at the panel id, and role=”button”.
Bootstrap’s Collapse docs still recommend a button for semantic reasons.
What can go inside an accordion body?
Nearly any HTML. Bootstrap’s docs say the body accepts just about any markup, so images, tables and forms all fit.
The one stated limit is that the height transition restricts overflow while it runs.
Is there a clean way to add an icon beside the header text?
Yes. Put the icon element inside the accordion-button, before the label, and add a margin utility such as me-2 for spacing.
Inside the button, the icon also counts as part of the click target.
Does the accordion work with panels added after page load?
Yes, for markup that uses data attributes. Bootstrap listens for clicks at the document level, so panels inserted later respond to their triggers.
Instances created by hand with new bootstrap.Collapse need the elements to exist first.
Testing a Bootstrap accordion before launch
Start with the attribute prefix and check it against the Bootstrap version that’s actually loaded. Then tab through every header and press Enter and Space on each one. Nested groups come last, tested on the exact version you ship.
The order follows blast radius. A wrong prefix disables every panel at once, a keyboard fault affects one input method, and nested grouping touches only pages that nest.
Verified against the 5.3.8 docs in October 2026, this sequence holds. The nested grouping bug was fixed in 5.1.2, so the last check matters most on sites that still run an older 5.1 release.
The cost is one manual pass per accordion, and a page-wide accessibility checklist covers the content around it.