Favorites

CSS Accordion - A Complete Guide

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee

What is an accordion?

An accordion is a stack of headings, each of which can be clicked to reveal more information underneath. Like the musical instrument, it expands and folds back up. You'll often see them on FAQ pages, product descriptions and settings menus.

Accordions are useful because they let visitors scan a list of topics quickly, then open only the ones they care about. That keeps long pages tidy, especially on small phone screens.

Here's the accordion we'll build. Click a heading to open it:

Results
Products

Browse our full range of CSS generators and tools.

Services

Find out how we can help with your next web project.

Contact us

Questions or feedback? We'd love to hear from you.

The old way and the new way

The original version of this tutorial built an accordion from a list of links and the :target pseudo-class, which styles whichever element's id matches the end of the page address. It worked, but it had problems: the page jumped every time you clicked a heading, every click was added to the browser's history, and screen readers couldn't tell the headings opened anything.

Today HTML has accordions built in, using the <details> and <summary> elements. They open and close with no JavaScript, no page jumping, and full keyboard and screen reader support. Our job with CSS is simply to make them look good.

Meet details and summary

The <details> element creates a box that can open and close. Inside it, the <summary> element is the heading that's always visible. Everything else inside <details> stays hidden until the summary is clicked.

<details>
  <summary>What is CSS?</summary>
  <p>CSS is the language used to style web pages.</p>
</details>

With no CSS at all, the browser already gives you a working toggle with a small triangle marker:

Results
What is CSS?

CSS is the language used to style web pages.

Starting open

Add the open attribute to have a panel already expanded when the page loads. The browser adds and removes this attribute as visitors click, which is also how we'll style the open state later.

<details open>
  <summary>Shipping information</summary>
  <p>Orders usually arrive within 3 to 5 working days.</p>
</details>

Key rule: the <summary> must be the first thing inside <details>. If it's missing, the browser adds a generic "Details" label instead.

Building the accordion

An accordion is simply several <details> elements stacked inside a wrapper. Wrapping each panel's content in a <div> makes it easy to add padding:

<div class="accordion">
  <details>
    <summary>Products</summary>
    <div class="accordion__content">
      <p>Content goes here...</p>
    </div>
  </details>
  <details>
    <summary>Services</summary>
    <div class="accordion__content">
      <p>Content goes here...</p>
    </div>
  </details>
  <details>
    <summary>Contact us</summary>
    <div class="accordion__content">
      <p>Content goes here...</p>
    </div>
  </details>
</div>

Now the outer container:

.accordion {
  max-width: 520px;
  border: 1px solid #d1d5db;
  border-radius: 10px;
  overflow: hidden;
  font: 1rem/1.5 system-ui, sans-serif;
}

.accordion details + details {
  border-top: 1px solid #e5e7eb;
}

.accordion__content {
  padding: 12px 18px 16px;
  color: #374151;
}

Line by line

LineWhat it does
max-width: 520px;Lets the accordion shrink on small screens but stops it growing too wide on large ones
border, border-radiusA light grey border with rounded corners around the whole accordion
overflow: hidden;Clips the headings' backgrounds to the rounded corners
fontA readable 1rem size using the device's own system font
details + detailsSelects every panel that comes straight after another one, adding a dividing line between them but not above the first
.accordion__contentPadding and a slightly softer text colour for the revealed content

What changed since the old version? The original used a fixed width: 250px and a 12px Verdana font. A max-width works on every screen size, and 1rem text is much easier to read on modern displays.

Styling the headings

The <summary> is our clickable heading. Let's give it a background, some padding and room for a custom icon:

.accordion summary {
  display: flex;
  justify-content: space-between;
  align-items: center;
  gap: 12px;
  padding: 14px 18px;
  font-weight: 600;
  color: #111827;
  background: #f8fafc;
  cursor: pointer;
  list-style: none;
  transition: background-color 0.2s ease;
}

.accordion summary::-webkit-details-marker {
  display: none;
}

.accordion summary:hover {
  background: #eff6ff;
}
  • display: flex with justify-content: space-between pushes the heading text to the left and our icon to the right.
  • cursor: pointer shows the hand cursor, so visitors know it's clickable.
  • list-style: none and the ::-webkit-details-marker rule remove the browser's default triangle. The second rule is needed for Safari.

A plus sign that turns into a cross

Now we add our own icon with the ::after pseudo-element, which inserts content using CSS alone. A plus sign works nicely, because rotating it 45 degrees turns it into a cross for the open state:

.accordion summary::after {
  content: "+";
  font-size: 1.5em;
  line-height: 1;
  font-weight: 400;
  color: #1d4ed8;
  transition: transform 0.2s ease;
}

.accordion details[open] > summary::after {
  transform: rotate(45deg);
}

The selector details[open] is an attribute selector: it matches a <details> element only while it has the open attribute. Since the browser adds and removes that attribute for us, the icon turns automatically.

A clear focus style

Keyboard users move between headings with the Tab key. Give them a clear outline so they can see where they are:

.accordion summary:focus-visible {
  outline: 3px solid #1d4ed8;
  outline-offset: -3px;
}

:focus-visible only shows the outline when someone is using the keyboard, not when they click with a mouse. The negative offset draws the outline just inside the heading so the container doesn't clip it.

One panel at a time

By default, each panel opens independently, so visitors can have several open at once. Often that's fine. But for a classic accordion, where opening one panel closes the others, just give every <details> in the group the same name:

<div class="accordion">
  <details name="faq"> ... </details>
  <details name="faq"> ... </details>
  <details name="faq"> ... </details>
</div>

The browser now treats them as a group and only allows one open at a time, much like radio buttons in a form. Try it below: opening one heading closes whichever was open before.

Results
Is this accordion free to use?

Yes. Copy the code into any personal or commercial project.

Does it need JavaScript?

No. Opening, closing and the one-at-a-time behaviour are all built into HTML.

Will it work on phones?

Yes. It works with taps, mouse clicks and the keyboard.

Good to know: the name attribute on <details> works in all current major browsers. In very old browsers, the panels simply open independently, so nothing breaks.

Animating open and close

Out of the box, panels snap open instantly. Animating them used to be tricky, because CSS couldn't animate to height: auto. Two newer features solve this:

  • interpolate-size: allow-keywords lets the browser animate between a number and a keyword like auto.
  • The ::details-content pseudo-element targets everything inside <details> except the summary, so we can animate its height.
.accordion {
  interpolate-size: allow-keywords;
}

.accordion details::details-content {
  block-size: 0;
  overflow: hidden;
  transition: block-size 0.3s ease, content-visibility 0.3s ease allow-discrete;
}

.accordion details[open]::details-content {
  block-size: auto;
}

block-size is the modern name for height in normal left-to-right text. The content-visibility part of the transition keeps the content visible until the closing animation finishes, rather than vanishing straight away.

Results
Smooth opening

In supporting browsers, this panel slides open and closed instead of snapping.

Progressive enhancement

In browsers without support, the panels still open and close instantly, so nothing is lost.

Good to know: these two features are newer and not yet in every browser. This is an example of progressive enhancement: browsers that understand the code get the animation, and the rest still get a fully working accordion.

As always with animation, turn it off for visitors who've asked their device to reduce motion:

@media (prefers-reduced-motion: reduce) {
  .accordion details::details-content,
  .accordion summary::after {
    transition: none;
  }
}

Accessibility and tips

One of the biggest advantages of <details> is how much it handles for you. Without any extra code:

  • keyboard users can tab to each heading and open it with Enter or Space
  • screen readers announce each heading as a button and say whether it's expanded or collapsed
  • in some browsers, using "find in page" automatically opens a panel that contains the word you're searching for

The old link-based version from 2013 couldn't do any of this without a lot of extra code.

Headings inside summary

On a long FAQ page, screen reader users often jump between headings to find what they want. You can put a heading element inside the summary so each question appears in that list:

<summary><h3>Is this accordion free to use?</h3></summary>

If you do, reset the heading's margin and font size in your CSS so it matches the rest of the summary.

When not to use an accordion

Accordions hide content, which means some visitors will never see it. Avoid them for information everyone needs to read, such as key steps in a process. They're best for optional detail, like FAQs or extra specifications, where visitors choose what to open.

Tip: if you're tempted to put an accordion inside another accordion, that's usually a sign the content needs reorganising into separate pages or sections instead.

The complete code

Here's all the CSS together, ready to copy:

.accordion {
  max-width: 520px;
  border: 1px solid #d1d5db;
  border-radius: 10px;
  overflow: hidden;
  font: 1rem/1.5 system-ui, sans-serif;
  interpolate-size: allow-keywords;
}

.accordion details + details {
  border-top: 1px solid #e5e7eb;
}

.accordion summary {
  display: flex;
  justify-content: space-between;
  align-items: center;
  gap: 12px;
  padding: 14px 18px;
  font-weight: 600;
  color: #111827;
  background: #f8fafc;
  cursor: pointer;
  list-style: none;
  transition: background-color 0.2s ease;
}
.accordion summary::-webkit-details-marker { display: none; }
.accordion summary:hover { background: #eff6ff; }
.accordion summary:focus-visible { outline: 3px solid #1d4ed8; outline-offset: -3px; }

.accordion summary::after {
  content: "+";
  font-size: 1.5em;
  line-height: 1;
  font-weight: 400;
  color: #1d4ed8;
  transition: transform 0.2s ease;
}
.accordion details[open] > summary::after { transform: rotate(45deg); }

.accordion__content {
  padding: 12px 18px 16px;
  color: #374151;
}

.accordion details::details-content {
  block-size: 0;
  overflow: hidden;
  transition: block-size 0.3s ease, content-visibility 0.3s ease allow-discrete;
}
.accordion details[open]::details-content { block-size: auto; }

@media (prefers-reduced-motion: reduce) {
  .accordion details::details-content,
  .accordion summary::after { transition: none; }
}

And the HTML:

<div class="accordion">
  <details name="faq" open>
    <summary>Products</summary>
    <div class="accordion__content">
      <p>Content goes here...</p>
    </div>
  </details>
  <details name="faq">
    <summary>Services</summary>
    <div class="accordion__content">
      <p>Content goes here...</p>
    </div>
  </details>
  <details name="faq">
    <summary>Contact us</summary>
    <div class="accordion__content">
      <p>Content goes here...</p>
    </div>
  </details>
</div>

Wrapping up

With <details> and <summary>, the browser does the hard work of opening, closing and accessibility, leaving CSS free to handle the looks. Add a name for one-at-a-time behaviour and a sprinkle of animation, and you have a polished accordion with no JavaScript at all.

☕
Enjoying this site?

Help keep it running with a small coffee donation. Every bit of support is appreciated!

Buy us a coffee