How to build a Tailwind accordion with details and summary
Tailwind doesn’t ship an accordion component. What you get is native details and summary elements with utility classes on top.
The browser handles the toggle and the keyboard activation, and it adds the open attribute for you. Tailwind just does spacing, borders and state styling.
Because the structure is plain HTML, the panels still open and close when a script fails to load.
A hand-written CSS accordion needs a stylesheet entry for every state. Here the same job lives in class names on the elements.
- Wrap each item in a
details element and put the question inside a summary. - Add
group to the details so its children can react to the open state. - Hide the default marker with
list-none on the summary, plus [&::-webkit-details-marker]:hidden for WebKit builds that still draw it. - Lay out the summary with
flex items-center justify-between gap-4 cursor-pointer so the icon sits at the far edge. - Add the chevron SVG after the label with
transition-transform group-open:rotate-180. - Pad the panel text, and add the
open attribute to any item that should start expanded. - Put
divide-y on the wrapper to separate the items.
<div class="divide-y divide-slate-200">
<details class="group py-3" open>
<summary class="flex cursor-pointer list-none items-center justify-between gap-4 [&::-webkit-details-marker]:hidden">
<span class="font-medium">What does the plan include?</span>
<svg class="size-4 transition-transform duration-200 group-open:rotate-180" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
</summary>
<p class="pt-2 text-sm text-slate-600">Three projects and email support.</p>
</details>
</div>
Style the open state
The only real difference between the variants is which element carries the state. The open: variant styles the details element itself, for example open:bg-slate-50. group-open: reaches any descendant of a group parent, like the icon or the panel text. And peer-open: styles a sibling that follows an element marked peer, which lets a panel outside the details react to it.
In Tailwind v4 the open variant matches both the open attribute and the :open pseudo-class, a change listed under the 4.0.1 release of January 29, 2025 in the Tailwind CSS changelog.
Nested accordions need named groups. An unnamed group-open: matches any open ancestor, so an inner icon would rotate when only the outer item is open.
Name the outer group with group/outer and target it with group-open/outer:. Rails Designer’s no-JavaScript tutorial uses the same group/details pattern.
Rotate the icon or swap plus for minus
I’d take an inline SVG chevron over an icon font every time. It inherits currentColor and rotates with one class, so nothing extra loads.
For a plus-minus swap, stack two icons. Put group-open:hidden on the plus and hidden group-open:block on the minus.
How to animate the accordion panel height
Transition grid-template-rows from 0fr to 1fr on a wrapper around the panel content.
A height swap from 0 to auto cannot interpolate, so the panel snaps open (Cruip). The grid method needs no fixed heights and no script to measure the content.
Grid track animation is supported from Chrome 107, Edge 107, Firefox 66 and Safari 16 (web.dev).
Grid-template-rows method
The wrapper is a grid with grid-rows-[0fr] when closed and grid-rows-[1fr] when open. Its single child needs overflow-hidden, or the content shows through the collapsed row.
With native details, mark the details as peer and place the wrapper right after it.
<details class="peer group">
<summary class="flex cursor-pointer list-none items-center justify-between py-3 [&::-webkit-details-marker]:hidden">
<span class="font-medium">Do you ship abroad?</span>
<svg class="size-4 transition-transform duration-200 group-open:rotate-180" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
</summary>
</details>
<div class="invisible grid grid-rows-[0fr] transition-[grid-template-rows,visibility] duration-300 ease-in-out peer-open:visible peer-open:grid-rows-[1fr]">
<div class="overflow-hidden">
<p class="pb-4 text-sm text-slate-600">Yes, we ship worldwide.</p>
</div>
</div>
The invisible class matters. A collapsed row still holds its links, and without it they stay in the tab order.
The catch is that a sibling panel gives up the find-in-page auto-expand that native details provides (Chrome for Developers, 2024). Content with visibility: hidden is skipped by the search.
Easing is the part worth previewing before you commit to a duration, so try a few curves in the browser before you settle on one.
max-height method
Set max-h-0 when closed and a cap such as max-h-96 when open. The cap must be larger than the tallest panel, or the content gets clipped.
Closing also feels delayed when the cap is far taller than the content, because the timer runs against the cap and not the real height.
Native animation with ::details-content
Native details can now animate without a sibling wrapper. Tailwind v4.1 added a details-content variant for the pseudo-element, and the transition-discrete utility sets transition-behavior: allow-discrete (Tailwind CSS documentation).
The ::details-content pseudo-element works in Chrome 131, Edge 131, Firefox 143 and Safari 18.4 (MDN browser compatibility data).
Then there’s interpolate-size: allow-keywords, which lets height animate to auto. It ships in Chrome 129 and Edge 129, and Firefox and Safari still do not support it as of October 2026 (MDN browser compatibility data), so wrap it in @supports.
Where support is missing, the accordion still works. Visitors only lose the animation.
Why a group-open fade does nothing
A group-open:opacity-100 transition on a panel inside details shows no animation. Closed content is not rendered, so the transition has nothing to start from.
On engines with ::details-content, the content-visibility flip is a discrete property. The transition needs transition-discrete as well, per the same Chrome for Developers article.
How to let only one panel stay open at a time
Give every details element in the group the same name attribute, and the browser closes the open one whenever another opens.
Tailwind has no utility for this. It is plain HTML, so the open: and group-open: styling keeps working unchanged.
<details name="shipping" class="group">
<summary>Delivery times</summary>
<p>Orders leave the warehouse in two working days.</p>
</details>
<details name="shipping" class="group">
<summary>Returns</summary>
<p>Unused items can be sent back within 30 days.</p>
</details>
Chrome and Edge support the name attribute from version 120 (Chrome for Developers, 2023). Safari picked it up in 17.2 and Firefox in 130. Baseline status has been newly available since September 3, 2024, with widely available status expected on March 3, 2027 (Web Platform DX feature explorer).
Multi-open is the default
Without a name, each details element toggles on its own, so several panels can stay open together.
Exclusive grouping is not always the better choice. The HTML Living Standard asks authors to weigh whether it helps or harms users, and Chrome’s team notes that visitors may have to open many items to read everything.
Grouping rules
- Members do not need to be siblings, because the name groups them and DOM order does not (Chrome for Developers)
- A new name value starts a separate group, so one page can hold several exclusive accordions
- Only one member of a group may carry the open attribute in the markup (HTML Living Standard)
- A details element cannot sit inside another member of its own group
Fallback for older browsers
The polyfill listens for the toggle event, finds the other open items with the same name and removes their open attribute (Chrome for Developers). It takes a few lines of JavaScript.
Basecoat UI ships its own script for the job instead. Its accordion keeps native details for the disclosure semantics, and the JavaScript enforces single-item behavior unless the root carries data-multiple (Basecoat UI documentation).
Check the support floors against your own cross-browser compatibility targets before dropping the script.
Browsers that do not fire the toggle event simply stay multi-open, which Chrome’s documentation calls acceptable progressive enhancement.
How to build a JavaScript-driven accordion with Alpine.js or React
Use a button and panel pair when the animation has to be exact, or when your framework needs to read the open state.
The markup contract is the same in every variant. The button carries aria-expanded and aria-controls, and the panel gets a matching id and role="region".
Cruip’s published Alpine.js version flips between grid-rows-[1fr] opacity-100 and grid-rows-[0fr] opacity-0 from a single expanded flag. The panel carries transition-all duration-300 ease-in-out.
Alpine.js
<div x-data="{ expanded: false }" class="border-b border-slate-200 py-2">
<button type="button" class="flex w-full items-center justify-between py-2 text-left font-medium" @click="expanded = !expanded" :aria-expanded="expanded" aria-controls="faq-1">
<span>Is there a free plan?</span>
<svg class="size-4 transition-transform duration-200" :class="expanded && 'rotate-180'" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m6 9 6 6 6-6" /></svg>
</button>
<div id="faq-1" role="region" class="grid text-sm text-slate-600 transition-all duration-300 ease-in-out" :class="expanded ? 'visible grid-rows-[1fr] opacity-100' : 'invisible grid-rows-[0fr] opacity-0'">
<div class="overflow-hidden">
<p class="pb-3">Yes. The free plan covers three projects.</p>
</div>
</div>
</div>
The visible and invisible classes are an addition to Cruip’s pattern. They keep collapsed links out of the tab order.
Alpine’s Collapse plugin is another route, and it animates height for you. It only works on an element that already has x-show, and the collapsed state sets height to 0px plus display: none by default (Alpine documentation).
The plugin script must load before Alpine’s core file.
React
Store the open item in one piece of state, such as const [openId, setOpenId] = useState(null). Comparing each item’s id to that value gives single-open behavior, and an array of ids gives multi-open.
The panel classes are the same grid classes, picked by a conditional string. If Tailwind is not wired into your build yet, start with the setup for Tailwind CSS in React.
Headless UI Disclosure
Disclosure and its button and panel parts manage the open state, and Enter or Space toggles the panel (Headless UI documentation). Styling is left entirely to you.
The open state reaches your classes through a render prop or data attributes. v2.1 reworked the transition API, so check your installed version before copying a snippet.
For a static FAQ, native details wins on weight. Headless UI earns its place when the accordion sits next to other Headless UI components.
Every build in this section depends on the script. Native details does not.
Which prebuilt library gives you a Tailwind accordion?
It comes down to how much JavaScript you accept. daisyUI needs none, Flowbite and Preline UI need their scripts, and shadcn/ui needs React.
All of them give you open-and-close behavior with Tailwind classes, and each charges a different price for it (as of October 2026).
Flowbite
Flowbite drives the accordion from data attributes.
data-accordion="collapse" keeps one child open at a timedata-accordion="open" keeps several children open- Each header button carries
data-accordion-target, aria-expanded and aria-controls
One attribute switches the mode, the ARIA attributes are already in the markup, and the core components are MIT-licensed (Flowbite documentation). The downside is that it needs Flowbite’s JavaScript, and it adds a data-attribute convention on top of your own classes.
daisyUI
daisyUI adds accordion styling as component classes, with no script involved. You write collapse, collapse-title and collapse-content, plus collapse-arrow or collapse-plus for the icon.
Exclusive behavior comes from radio inputs or details elements that share a name, and a second accordion on the page needs a different name (daisyUI documentation).
The details variant keeps collapsed text searchable in the browser, and the icon modifiers replace hand-built SVG rotation. That’s most of the appeal, since there’s no JavaScript at all.
Some rough edges exist. The collapse-open and collapse-close modifiers do not work with the details variant, so the open attribute does that job. The checkbox and radio variants hide collapsed text from in-browser search, which is why the docs point to the details variant.
Preline UI
Preline’s accordion page carries a “Requires JS” label.
Setup starts with npm i @preline/accordion. After that comes an @source line plus the plugin’s variants.css and theme.css imports in your Tailwind CSS file, and last the plugin script.
Markup uses hs-accordion, hs-accordion-toggle and hs-accordion-content. A global HSAccordion object exposes methods such as show() for programmatic control.
In return you get a JavaScript API, lifecycle events, ARIA attributes built in and a height transition on the panel. What it costs is a plugin script and an extra import step in your Tailwind CSS file.
shadcn/ui and Radix UI
The shadcn/ui accordion is copied into your project with pnpm dlx shadcn@latest add accordion. Its docs now default to a Base UI version and also offer React Aria and Radix UI versions. Supabase’s design system documents its accordion as a Radix UI component built with shadcn/ui.
In the Radix UI version, with type="single" and collapsible, the open item can close again. type="multiple" allows several open at once. For styling, data-state reads open or closed on the trigger and content, so data-[state=open]: variants work.
Animation takes a bit more setup. Radix exposes --radix-accordion-content-height, and its docs animate height from 0 to that variable with keyframes.
The upside is accessibility handled for you, since the component follows the WAI-ARIA accordion pattern (Radix UI documentation).
The downside is React-only code, Radix as a dependency, and keyframes you register yourself.
How to make a Tailwind accordion accessible
The WAI-ARIA Authoring Practices accordion pattern sets the keyboard rules.
- Enter or Space toggles the panel of the focused header
- Tab and Shift+Tab move through all focusable elements in the accordion, panel links included
Native details covers both. The pattern used to list Down Arrow, Up Arrow, Home and End as optional extras, but the APG editors removed them in April 2026. Radix UI still ships those keys, which does no harm.
Red Hat’s design system describes the same model, with each panel header as a focus stop where Enter or Space expands or collapses it.
Native elements already carry their own semantics, so extra ARIA roles on a summary cause trouble.
Native summary support is uneven
On paper it looks fine. Most browsers expose the summary element as a button, so screen readers announce it as one, and W3C’s ARIA in HTML allows no role attribute on a summary that labels its details.
Real-world results look worse. a11ysupport.io lists the summary element at partial support, 38/44 for screen readers and 5/13 for voice control, and warns that its oldest results are five years old.
The two disagree because one describes the specified mapping and the other records what real browser and screen reader pairs do.
Scott O’Hara’s 2018 write-up found the same gap. With role="button" added to a summary, NVDA with Chrome stopped announcing the state change, and VoiceOver could no longer reach a heading nested inside.
Use the bare summary. The override removes the state announcement instead of fixing the gap.
Headings, focus and motion
Header buttons in custom builds belong inside a heading element.
Flowbite wraps its button in an h2, and Radix UI’s Accordion.Header wraps the trigger, with asChild to set the level for your page.
- In native details, keep headings out of the summary because screen readers handle them unevenly. JAWS does not announce a heading inside a summary, TalkBack ignores it, and NVDA with Chrome stopped announcing the state change when one sat inside (Scott O’Hara, 2018 tests)
- Match the heading level to the page outline, not to the accordion’s visual size
- Add
focus-visible:ring-2 to every summary or button, since outline-none removes the default focus indicator - Put
motion-reduce:transition-none on animated panels and icons, a variant Tailwind has shipped since v1.6.0 (Tailwind CSS blog)
Where Tailwind accordions break
Most failures come from a script that never loads or a layout assumption that clashes with ::details-content. The other kind comes from content that never belonged in an accordion.
When the script does not load
Flowbite and Preline UI both need their JavaScript before anything opens.
Flowbite’s collapsed panels carry the hidden class in the published markup, so the text stays hidden if the script never runs. Preline’s published markup does the same, with hidden on every collapsed hs-accordion-content panel.
Native details and daisyUI’s details variant degrade differently. The text stays reachable, and the toggle belongs to the browser.
When ::details-content changes your layout
Chrome 131 (November 2024) set the display of ::details-content to block in the user-agent stylesheet, where it used to behave as display: contents.
Panel content that relies on height: 100% can break as a result.
Chrome’s documentation gives the workaround, details[open]::details-content { display: contents; }, which restores the old behavior.
When the content should not be hidden at all
An accordion hides text by default. It suits secondary answers, not anything a visitor must read to decide.
Pricing terms and legal limits should stay in plain view. So should steps the reader has to follow in order. Sections that visitors compare side by side are a poor fit too.
For parallel views of equal weight, a Tailwind tabs layout shows every label at once. Plain headings with open text handle the rest.
How to choose between native, JavaScript and library accordions
Use native details unless you need behavior it cannot give you, and reach for a library only when the rest of your interface already runs on one.
| Approach | JavaScript | Animation | Single-open |
|---|
| Native details | None | Grid sibling or ::details-content | name attribute |
| JavaScript-driven build | Required | Grid classes or Alpine’s Collapse plugin | Shared state |
| Prebuilt library | Depends on the library | Built in, or keyframes you add | Prop, attribute or shared name |
A static FAQ or docs page is well served by native details with group-open: styling. If the open state feeds other UI, go with a JavaScript-driven build, because the state has to live in a variable something else can read. And when the project already sits on a component system, use that system’s accordion so buttons, modals and accordions share one set of tokens.
Each step up adds weight. A JavaScript build adds the script and the ARIA wiring, and a library adds a dependency plus a convention to learn.
Out of the box, native details brings disclosure semantics (with the uneven screen reader support described above), and daisyUI’s details variant inherits them. Flowbite’s markup includes ARIA attributes, Radix UI follows the WAI-ARIA accordion pattern, and in a hand-built build the wiring is yours.
Installing a library for a single FAQ is overbuilt. If one is justified, daisyUI’s details variant costs the least, since it needs no script.
Tailwind accordion FAQ
How do you style a Tailwind accordion for dark mode?
Add dark: variants to the summary, panel and border classes, such as bg-white dark:bg-slate-900.
In Tailwind v4 the variant follows prefers-color-scheme with no setup. A manual toggle needs @custom-variant dark (&:where(.dark, .dark *)); in your CSS.
Does the accordion code change in Tailwind v4?
Not much. The group-open:, open: and peer-open: classes work the same way.
The difference is how variants combine. Stacked variants apply left to right in v4, not right to left, so reorder any stack carried over from v3.
Can you nest accordions inside each other?
Yes. Name the groups group/outer and group/inner, and style each level with group-open/outer: or group-open/inner:.
With the grid height method, the outer row grows as the inner panel opens. In single-open mode, give the inner details a different name value than the outer ones.
How do you change the animation speed?
Set a duration utility on the element that carries the transition, such as duration-500 for 500ms, or duration-[400ms] for a one-off value.
The panel and the chevron transition separately, so give both the same duration or the icon finishes before the panel does.
How to check a Tailwind accordion before launch
Test keyboard operation first, then screen reader announcements, and last the oldest browser on your support list.
Keyboard checks need no extra software. Screen reader results decide whether native summary markup stays, and a missing browser feature costs only the animation or the single-open behavior, never the toggle.
In every engine, the ::details-content release comes later than the name attribute release, so the animation feature sets the floor for a fully native build.
Reassess the sibling panel once the oldest supported browser clears that floor (position verified October 2026).
A full web accessibility checklist extends the same checks to the rest of the page.