Building an Accordion/Collapsible Component

Build an Accordion component for MDX — animated expand/collapse, grouped panels, FAQ patterns, and proper ARIA support.

Accordions let you hide content behind clickable headers. Readers scan the titles, expand what they care about, and skip the rest. They're perfect for FAQs, API references, long code examples — anything where showing everything at once would overwhelm the page.

Why Accordions in MDX?

Long docs pages scare people off. Accordions give readers a way to scan quickly and drill into just the parts they need. All the info stays on one page, but it doesn't hit them in the face all at once.

Component Source Code

Here's the full Accordion system with smooth height animations:

Example

// components/Accordion.jsx import React, { useState, useRef, useEffect, createContext, useContext } from 'react'; // Context for Accordion Groups (single-open behavior) const AccordionGroupContext = createContext(null); // Accordion Group - ensures only one item is open at a time export function AccordionGroup({ children, allowMultiple = false, className = '' }) { const [openItems, setOpenItems] = useState(new Set()); const toggleItem = (id) => { setOpenItems((prev) => { const next = new Set(prev); if (next.has(id)) { next.delete(id); } else { if (!allowMultiple) next.clear(); next.add(id); } return next; }); }; const isOpen = (id) => openItems.has(id); return ( <AccordionGroupContext.Provider value={{ toggleItem, isOpen }}> <div className={`divide-y divide-gray-200 dark:divide-gray-700 border border-gray-200 dark:border-gray-700 rounded-lg overflow-hidden ${className}`}> {children} </div> </AccordionGroupContext.Provider> ); } // Single Accordion Item export function Accordion({ id, title, children, defaultOpen = false, icon, className = '', }) { const groupContext = useContext(AccordionGroupContext); const [internalOpen, setInternalOpen] = useState(defaultOpen); const contentRef = useRef(null); const [contentHeight, setContentHeight] = useState(0); // Determine if controlled by group or standalone const isOpen = groupContext ? groupContext.isOpen(id) : internalOpen; const toggle = groupContext ? () => groupContext.toggleItem(id) : () => setInternalOpen((prev) => !prev); // Measure content height for animation useEffect(() => { if (contentRef.current) { setContentHeight(contentRef.current.scrollHeight); } }, [children]); // Generate a unique ID for ARIA if not provided const accordionId = id || `accordion-${Math.random().toString(36).slice(2)}`; return ( <div className={`${groupContext ? '' : 'border border-gray-200 dark:border-gray-700 rounded-lg overflow-hidden my-3'} ${className}`}> {/* Trigger Button */} <button onClick={toggle} aria-expanded={isOpen} aria-controls={`content-${accordionId}`} id={`trigger-${accordionId}`} className={` w-full flex items-center justify-between px-5 py-4 text-left font-medium text-gray-900 dark:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-inset transition-colors duration-150 `} > <span className="flex items-center gap-3"> {icon && <span aria-hidden="true">{icon}</span>} {title} </span> {/* Chevron indicator */} <svg className={`w-5 h-5 text-gray-500 transition-transform duration-300 ${isOpen ? 'rotate-180' : ''}`} fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true" > <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" /> </svg> </button> {/* Collapsible Content */} <div id={`content-${accordionId}`} role="region" aria-labelledby={`trigger-${accordionId}`} style={{ maxHeight: isOpen ? `${contentHeight}px` : '0px', opacity: isOpen ? 1 : 0, }} className="overflow-hidden transition-all duration-300 ease-in-out" > <div ref={contentRef} className="px-5 pb-4 pt-2 text-gray-700 dark:text-gray-300"> {children} </div> </div> </div> ); }

Basic Usage in MDX

Drop in a single standalone accordion like this:

mdx example

import { Accordion } from '../components/Accordion';

# Getting Started

<Accordion title="System Requirements" defaultOpen>
  - Node.js 18 or later
  - npm 8+ or yarn 1.22+
  - A code editor (VS Code recommended)
  - Git for version control
</Accordion>

<Accordion title="Optional Dependencies">
  These packages are optional but enhance your experience:
  - `prettier` — for code formatting
  - `eslint` — for code linting
  - `husky` — for git hooks
</Accordion>

Accordion Group (Single Open)

Want only one accordion open at a time? Wrap them in an AccordionGroup. When you click one, the others close:

mdx example

import { Accordion, AccordionGroup } from '../components/Accordion';

# API Reference

<AccordionGroup>
  <Accordion id="get-users" title="GET /api/users">
    Retrieves a list of all users in the system.

    **Parameters:**
    - `limit` (optional) — Maximum results to return
    - `offset` (optional) — Pagination offset

    **Response:** `200 OK` with JSON array of user objects.
  </Accordion>

  <Accordion id="post-users" title="POST /api/users">
    Creates a new user in the system.

    **Body:**

{ "name": "John Doe", "email": "john@example.com" }

mdx example


    **Response:** `201 Created` with the new user object.
  </Accordion>

  <Accordion id="delete-users" title="DELETE /api/users/:id">
    Permanently removes a user from the system.

    **Parameters:**
    - `id` (required) — The user's unique identifier

    **Response:** `204 No Content`
  </Accordion>
</AccordionGroup>

Allow Multiple Open

If you want users to expand several panels at once, pass allowMultiple:

mdx example

<AccordionGroup allowMultiple>
  <Accordion id="section-1" title="Section One">
    This section can be open simultaneously with others.
  </Accordion>

  <Accordion id="section-2" title="Section Two">
    Multiple sections can be expanded at the same time.
  </Accordion>

  <Accordion id="section-3" title="Section Three">
    The allowMultiple prop enables this behavior.
  </Accordion>
</AccordionGroup>

Initially Open State

Need something visible right away? Use defaultOpen:

mdx example

<Accordion title="Important: Read First" defaultOpen>
  This accordion starts in the expanded state so readers
  see the content immediately. Useful for critical
  information or introductory notes.
</Accordion>

FAQ Pattern

Accordions are a natural fit for FAQ pages:

mdx example

import { Accordion, AccordionGroup } from '../components/Accordion';

# Frequently Asked Questions

<AccordionGroup>
  <Accordion id="faq-1" title="What is MDX?">
    MDX is a format that lets you write JSX directly in your
    Markdown documents. You can import components, use them inline
    with your text content, and even export data from your MDX files.
  </Accordion>

  <Accordion id="faq-2" title="Is MDX compatible with existing Markdown?">
    Yes! MDX is a superset of Markdown. All valid Markdown is also
    valid MDX. You can gradually adopt components without rewriting
    existing content.
  </Accordion>

  <Accordion id="faq-3" title="What frameworks support MDX?">
    MDX works with Next.js, Gatsby, Remix, Astro, Docusaurus,
    and many other React-based frameworks. There's also support
    for Vue and Svelte through community plugins.
  </Accordion>

  <Accordion id="faq-4" title="How do I style MDX components?">
    You can use CSS Modules, Tailwind CSS, styled-components,
    Emotion, or any other CSS-in-JS solution. The components
    are just React components, so any styling approach works.
  </Accordion>
</AccordionGroup>

Nested Accordions

You can nest them for hierarchical content:

mdx example

<Accordion title="Frontend Technologies">
  <AccordionGroup>
    <Accordion id="react" title="React" icon="⚛️">
      A JavaScript library for building user interfaces.
      React uses a component-based architecture and virtual DOM.
    </Accordion>

    <Accordion id="vue" title="Vue.js" icon="💚">
      A progressive framework for building user interfaces.
      Vue is designed to be incrementally adoptable.
    </Accordion>

    <Accordion id="svelte" title="Svelte" icon="🔥">
      A compiler that converts components into efficient
      imperative code that directly manipulates the DOM.
    </Accordion>
  </AccordionGroup>
</Accordion>

Accordion with Icons

Add emoji or icon elements before the title:

Example

<AccordionGroup> <Accordion id="setup" title="Setup & Installation" icon="🔧"> Step-by-step installation instructions... </Accordion> <Accordion id="config" title="Configuration" icon="⚙️"> Configuration options and settings... </Accordion> <Accordion id="deploy" title="Deployment" icon="🚀"> Deployment guides for various platforms... </Accordion> </AccordionGroup>

Props API Documentation

AccordionGroup Props

Prop	Type	Default	Description
`allowMultiple`	`boolean`	`false`	Allow multiple items to be open simultaneously
`children`	`ReactNode`	required	Accordion items
`className`	`string`	`''`	Additional CSS classes

Accordion Props

Prop	Type	Default	Description
`id`	`string`	auto-generated	Unique identifier (required when inside AccordionGroup)
`title`	`string \	ReactNode`	required	The accordion trigger label
`defaultOpen`	`boolean`	`false`	Whether the accordion starts expanded
`icon`	`ReactNode`	`undefined`	Icon shown before the title
`children`	`ReactNode`	required	Collapsible content
`className`	`string`	`''`	Additional CSS classes

Styling with CSS

If you'd rather use plain CSS instead of Tailwind:

Example

/* Accordion.module.css */ .accordion-group { border: 1px solid #e5e7eb; border-radius: 0.5rem; overflow: hidden; divide: 1px solid #e5e7eb; } .accordion-item { border-bottom: 1px solid #e5e7eb; } .accordion-item:last-child { border-bottom: none; } .accordion-trigger { width: 100%; display: flex; align-items: center; justify-content: space-between; padding: 1rem 1.25rem; text-align: left; font-weight: 500; color: #111827; background: none; border: none; cursor: pointer; transition: background-color 0.15s; } .accordion-trigger:hover { background-color: #f9fafb; } .accordion-trigger:focus-visible { outline: 2px solid #2563eb; outline-offset: -2px; } .accordion-chevron { width: 1.25rem; height: 1.25rem; color: #6b7280; transition: transform 0.3s ease; } .accordion-chevron[data-open="true"] { transform: rotate(180deg); } .accordion-content { overflow: hidden; transition: max-height 0.3s ease, opacity 0.3s ease; } .accordion-content[data-state="closed"] { max-height: 0; opacity: 0; } .accordion-content[data-state="open"] { opacity: 1; } .accordion-content-inner { padding: 0.5rem 1.25rem 1rem; color: #374151; }

Animated Transitions Deep Dive

The animation relies on max-height and opacity transitions. Here's why:

jsx example

// The key animation technique:
style={{
  maxHeight: isOpen ? `${contentHeight}px` : '0px',
  opacity: isOpen ? 1 : 0,
}}
className="overflow-hidden transition-all duration-300 ease-in-out"

Why max-height instead of height? CSS can't transition from height: 0 to height: auto. By measuring scrollHeight and setting an explicit pixel value for max-height, you get a smooth animation.

Alternative: CSS Grid animation (works in modern browsers):

Example

.accordion-content { display: grid; grid-template-rows: 0fr; transition: grid-template-rows 0.3s ease; } .accordion-content[data-state="open"] { grid-template-rows: 1fr; } .accordion-content > div { overflow: hidden; }

Accessibility Notes

Here's what makes this accessible:

aria-expanded — The button tells screen readers whether the panel is open or closed.

aria-controls — Links the button to the content it toggles, so assistive tech can jump between them.

role="region" — The panel is marked as a region with aria-labelledby pointing back to the button.

Keyboard interaction — It's a native <button>, so Enter and Space work out of the box.

Focus management — focus-visible styles show clear focus rings for keyboard users without affecting mouse users.

Content accessibility — When collapsed, overflow: hidden with zero height hides content visually. The final closed state keeps it hidden from screen readers too.

Motion sensitivity — Add a prefers-reduced-motion query for users who get motion sickness:

css example

@media (prefers-reduced-motion: reduce) {
  .accordion-content {
    transition: none;
  }
  .accordion-chevron {
    transition: none;
  }
}

Advanced: Searchable FAQ Accordion

For long FAQ lists, add a search filter:

Example

export function SearchableFAQ({ items }) { const [search, setSearch] = useState(''); const filtered = items.filter( (item) => item.question.toLowerCase().includes(search.toLowerCase()) || item.answer.toLowerCase().includes(search.toLowerCase()) ); return ( <div> <input type="search" placeholder="Search FAQ..." value={search} onChange={(e) => setSearch(e.target.value)} className="w-full px-4 py-2 mb-4 border rounded-lg" aria-label="Search frequently asked questions" /> <AccordionGroup> {filtered.map((item) => ( <Accordion key={item.id} id={item.id} title={item.question}> {item.answer} </Accordion> ))} </AccordionGroup> {filtered.length === 0 && ( <p className="text-gray-500 text-center py-4"> No results found for "{search}" </p> )} </div> ); }

Summary

The Accordion is all about progressive disclosure — show titles upfront, reveal details on demand. With smooth animations, ARIA attributes, and flexible group/standalone modes, this component makes long MDX docs way easier to navigate.

Why Accordions in MDX?

Component Source Code

Here's the full Accordion system with smooth height animations:

Example

Basic Usage in MDX

Drop in a single standalone accordion like this:

mdx example

import { Accordion } from '../components/Accordion';

# Getting Started

<Accordion title="System Requirements" defaultOpen>
  - Node.js 18 or later
  - npm 8+ or yarn 1.22+
  - A code editor (VS Code recommended)
  - Git for version control
</Accordion>

<Accordion title="Optional Dependencies">
  These packages are optional but enhance your experience:
  - `prettier` — for code formatting
  - `eslint` — for code linting
  - `husky` — for git hooks
</Accordion>

Accordion Group (Single Open)

Want only one accordion open at a time? Wrap them in an AccordionGroup. When you click one, the others close:

mdx example

import { Accordion, AccordionGroup } from '../components/Accordion';

# API Reference

<AccordionGroup>
  <Accordion id="get-users" title="GET /api/users">
    Retrieves a list of all users in the system.

    **Parameters:**
    - `limit` (optional) — Maximum results to return
    - `offset` (optional) — Pagination offset

    **Response:** `200 OK` with JSON array of user objects.
  </Accordion>

  <Accordion id="post-users" title="POST /api/users">
    Creates a new user in the system.

    **Body:**

{ "name": "John Doe", "email": "john@example.com" }

mdx example


    **Response:** `201 Created` with the new user object.
  </Accordion>

  <Accordion id="delete-users" title="DELETE /api/users/:id">
    Permanently removes a user from the system.

    **Parameters:**
    - `id` (required) — The user's unique identifier

    **Response:** `204 No Content`
  </Accordion>
</AccordionGroup>

Allow Multiple Open

If you want users to expand several panels at once, pass allowMultiple:

mdx example

<AccordionGroup allowMultiple>
  <Accordion id="section-1" title="Section One">
    This section can be open simultaneously with others.
  </Accordion>

  <Accordion id="section-2" title="Section Two">
    Multiple sections can be expanded at the same time.
  </Accordion>

  <Accordion id="section-3" title="Section Three">
    The allowMultiple prop enables this behavior.
  </Accordion>
</AccordionGroup>

Initially Open State

Need something visible right away? Use defaultOpen:

mdx example

<Accordion title="Important: Read First" defaultOpen>
  This accordion starts in the expanded state so readers
  see the content immediately. Useful for critical
  information or introductory notes.
</Accordion>

FAQ Pattern

Accordions are a natural fit for FAQ pages:

mdx example

import { Accordion, AccordionGroup } from '../components/Accordion';

# Frequently Asked Questions

<AccordionGroup>
  <Accordion id="faq-1" title="What is MDX?">
    MDX is a format that lets you write JSX directly in your
    Markdown documents. You can import components, use them inline
    with your text content, and even export data from your MDX files.
  </Accordion>

  <Accordion id="faq-2" title="Is MDX compatible with existing Markdown?">
    Yes! MDX is a superset of Markdown. All valid Markdown is also
    valid MDX. You can gradually adopt components without rewriting
    existing content.
  </Accordion>

  <Accordion id="faq-3" title="What frameworks support MDX?">
    MDX works with Next.js, Gatsby, Remix, Astro, Docusaurus,
    and many other React-based frameworks. There's also support
    for Vue and Svelte through community plugins.
  </Accordion>

  <Accordion id="faq-4" title="How do I style MDX components?">
    You can use CSS Modules, Tailwind CSS, styled-components,
    Emotion, or any other CSS-in-JS solution. The components
    are just React components, so any styling approach works.
  </Accordion>
</AccordionGroup>

Nested Accordions

You can nest them for hierarchical content:

mdx example

<Accordion title="Frontend Technologies">
  <AccordionGroup>
    <Accordion id="react" title="React" icon="⚛️">
      A JavaScript library for building user interfaces.
      React uses a component-based architecture and virtual DOM.
    </Accordion>

    <Accordion id="vue" title="Vue.js" icon="💚">
      A progressive framework for building user interfaces.
      Vue is designed to be incrementally adoptable.
    </Accordion>

    <Accordion id="svelte" title="Svelte" icon="🔥">
      A compiler that converts components into efficient
      imperative code that directly manipulates the DOM.
    </Accordion>
  </AccordionGroup>
</Accordion>

Accordion with Icons

Add emoji or icon elements before the title:

Example

Props API Documentation

AccordionGroup Props

Prop	Type	Default	Description
`allowMultiple`	`boolean`	`false`	Allow multiple items to be open simultaneously
`children`	`ReactNode`	required	Accordion items
`className`	`string`	`''`	Additional CSS classes

Accordion Props

Prop	Type	Default	Description
`id`	`string`	auto-generated	Unique identifier (required when inside AccordionGroup)
`title`	`string \	ReactNode`	required	The accordion trigger label
`defaultOpen`	`boolean`	`false`	Whether the accordion starts expanded
`icon`	`ReactNode`	`undefined`	Icon shown before the title
`children`	`ReactNode`	required	Collapsible content
`className`	`string`	`''`	Additional CSS classes

Styling with CSS

If you'd rather use plain CSS instead of Tailwind:

Example

Animated Transitions Deep Dive

The animation relies on max-height and opacity transitions. Here's why:

jsx example

// The key animation technique:
style={{
  maxHeight: isOpen ? `${contentHeight}px` : '0px',
  opacity: isOpen ? 1 : 0,
}}
className="overflow-hidden transition-all duration-300 ease-in-out"

Alternative: CSS Grid animation (works in modern browsers):

Example

Accessibility Notes

Here's what makes this accessible:

aria-expanded — The button tells screen readers whether the panel is open or closed.

aria-controls — Links the button to the content it toggles, so assistive tech can jump between them.

role="region" — The panel is marked as a region with aria-labelledby pointing back to the button.

Keyboard interaction — It's a native <button>, so Enter and Space work out of the box.

Focus management — focus-visible styles show clear focus rings for keyboard users without affecting mouse users.

Content accessibility — When collapsed, overflow: hidden with zero height hides content visually. The final closed state keeps it hidden from screen readers too.

Motion sensitivity — Add a prefers-reduced-motion query for users who get motion sickness:

css example

@media (prefers-reduced-motion: reduce) {
  .accordion-content {
    transition: none;
  }
  .accordion-chevron {
    transition: none;
  }
}

Advanced: Searchable FAQ Accordion

For long FAQ lists, add a search filter:

Example

Building an Accordion/Collapsible Component

Why Accordions in MDX?

Component Source Code

Basic Usage in MDX

Accordion Group (Single Open)

Allow Multiple Open

Initially Open State

FAQ Pattern

Nested Accordions

Accordion with Icons

Props API Documentation

AccordionGroup Props

Accordion Props

Styling with CSS

Animated Transitions Deep Dive

Accessibility Notes

Advanced: Searchable FAQ Accordion

Summary

Continue learning this concept

Building an Accordion/Collapsible Component

Why Accordions in MDX?

Component Source Code

Basic Usage in MDX

Accordion Group (Single Open)

Allow Multiple Open

Initially Open State

FAQ Pattern

Nested Accordions

Accordion with Icons

Props API Documentation

AccordionGroup Props

Accordion Props

Styling with CSS

Animated Transitions Deep Dive

Accessibility Notes

Advanced: Searchable FAQ Accordion

Summary

Continue learning this concept