Building an Accessible Category Accordion Without Third-Party Libraries

Organizing blog posts by category does not need a third-party accordion library. The native <details> and <summary> elements handle disclosure behavior, keyboard support, and screen reader semantics for free, which means less JavaScript to ship and less surface area to maintain.

The Power of HTML5 details/summary

<details> and <summary> provide native accordion functionality with built-in accessibility:

1
<details>
2
  <summary>Category Name</summary>
3
  <div>Content goes here...</div>
4
</details>

These elements give you:

• Native keyboard navigation (Enter and Space toggle the summary)
• Built-in ARIA state, exposed automatically as the open attribute changes
• Screen reader support with no extra aria-* wiring
• Default open and closed states via the open attribute

Building the Category Accordion

Here is the component, written as an Astro island:

1
---
2
import type { CollectionEntry } from "astro:content";
3
import PostList from "./PostList.astro";
4

5
type Props = {
6
  category: string;
7
  posts: CollectionEntry<"posts">[];
8
  isOpen?: boolean;
9
};
10

11
const { category, posts, isOpen = false } = Astro.props;
12

13
// Filter posts for this category
14
const categoryPosts = posts.filter((post) =>
15
  post.data.categories.includes(category)
16
);
17
---
18

19
<div class="border-b border-teal-900/20 dark:border-zinc-700">
20
  <details class="group" open={isOpen}>
21
    <summary
22
      class="flex cursor-pointer list-none items-center justify-between py-4 text-xl font-medium text-zinc-900 dark:text-zinc-100"
23
    >
24
      <div class="flex items-center gap-x-3">
25
        <span
26
          class="inline-flex h-8 w-8 items-center justify-center rounded-full bg-teal-100 text-sm font-medium text-teal-900 dark:bg-zinc-800 dark:text-zinc-200"
27
        >
28
          {categoryPosts.length}
29
        </span>
30
        <span>{category}</span>
31
      </div>
32
      <svg
33
        class="h-5 w-5 rotate-0 transform text-zinc-500 transition duration-300 ease-in-out group-open:rotate-180 dark:text-zinc-400"
34
        xmlns="http://www.w3.org/2000/svg"
35
        fill="none"
36
        viewBox="0 0 24 24"
37
        stroke-width="2"
38
        stroke="currentColor"
39
      >
40
        <path
41
          stroke-linecap="round"
42
          stroke-linejoin="round"
43
          d="M19.5 8.25l-7.5 7.5-7.5-7.5"
44
        ></path>
45
      </svg>
46
    </summary>
47
    <div class="pb-6">
48
      <PostList posts={categoryPosts} />
49
    </div>
50
  </details>
51
</div>
52

53
<style>
54
  details summary::-webkit-details-marker {
55
    display: none;
56
  }
57
</style>

1. Accessibility first

<details> and <summary> provide native accessibility for free:

• Keyboard navigation with Enter and Space
• Correct ARIA roles and states, generated by the browser
• Screen reader announcements when the section opens or closes

2. Visual enhancements

A few CSS rules replace the default marker with a rotating chevron:

1
/* Remove default triangle marker */
2
details summary::-webkit-details-marker {
3
  display: none;
4
}
5

6
/* Custom arrow icon with smooth rotation */
7
.group-open\:rotate-180 {
8
  transform: rotate(180deg);
9
}
10

11
.transition {
12
  transition-property: transform;
13
  transition-duration: 300ms;
14
  transition-timing-function: ease-in-out;
15
}

Note the escaped colon in .group-open\:rotate-180: Tailwind’s group-open: variant compiles to a class name with a literal colon, which needs escaping in raw CSS. When you write it as a Tailwind utility class in markup (group-open:rotate-180), Tailwind handles the escaping for you.

3. Post count badge

A circular badge shows how many posts sit in each category:

1
<span class="inline-flex h-8 w-8 items-center justify-center rounded-full bg-teal-100">
2
  {categoryPosts.length}
3
</span>

4. Dark mode support

Tailwind’s dark: modifier covers the color scheme:

1
<div class="text-zinc-900 dark:text-zinc-100">
2
  <!-- Content -->
3
</div>

Using the Accordion

1
<CategoryAccordion
2
  category="WebDevelopment"
3
  posts={allPosts}
4
  isOpen={true}
5
/>

Benefits Over Third-Party Libraries

1. Performance: zero additional JavaScript bundle.
2. Accessibility: native elements come with screen reader support already correct.
3. Maintainability: nothing to patch when a library ships a breaking change.
4. Customization: full control over markup and styling.
5. SEO: semantic HTML that crawlers parse without extra hints.

Browser Support

<details> and <summary> are supported in every browser still in active use: Chrome, Firefox, Safari, and Edge have all shipped support for over a decade. The ::-webkit-details-marker pseudo-element used to hide the default triangle is WebKit-specific; Firefox and Chromium-based browsers other than the original marker rendering may need a list-style: none fallback if you see a residual marker.

Conclusion

An accessible accordion does not require a dependency. Native HTML5 elements plus a small amount of CSS produce a component that is faster, more maintainable, and no less accessible than a library-based one.

If you are taking this into production, the next steps below cover auth, data and observability, and the newsletter is where the Astro SaaS boilerplate ships first.