Accordion
Introduction
The Accordion component provides an expandable/collapsible section of content that follows the WAI-ARIA best practices. It uses the native HTML <details>
and <summary>
elements for built-in accessibility and functionality.
When to use
Accordions are perfect for progressive disclosure of content, allowing users to focus on specific information while keeping the interface clean and organized. They’re especially useful for:
- FAQ sections
- Content that needs to be shown/hidden
- Settings panels
- Any content that benefits from progressive disclosure
Usage
Learn how to implement the Accordion component in your project, from basic usage to advanced variants.
Basic
---import { Accordion, AccordionItem } from 'accessible-astro-components'---
<Accordion> <AccordionItem name="astro" title="What is Astro?" open > <p>Astro is an all-in-one web framework for building fast, content-focused websites.</p> </AccordionItem> <AccordionItem name="astro" title="Why Astro?" > <p>Ship less JavaScript to your users while maintaining a modern developer experience.</p> </AccordionItem></Accordion>
Variants
The AccordionItem component offers flexibility in its visual presentation through two distinct styles using the variant
prop, allowing you to choose the one that best fits your design needs.
<Accordion> {/* Default variant with plus/minus icon */} <AccordionItem title="Default Style"> <p>Uses a plus/minus icon on the left</p> </AccordionItem>
{/* Chevron variant with arrow on the right */} <AccordionItem title="Chevron Style" variant="chevron" > <p>Uses a chevron icon on the right</p> </AccordionItem></Accordion>
Props
Configure the Accordion and AccordionItem components using these available props to customize their behavior and appearance.
Accordion
Prop | Type | Default | Description |
---|---|---|---|
class | string | '' | Additional CSS classes to apply to the accordion wrapper |
AccordionItem
Prop | Type | Default | Description |
---|---|---|---|
name | string | '' | Optional group name for exclusive opening behavior |
title | string | required | The header text for the accordion item |
class | string | '' | Additional CSS classes to apply to the item |
variant | 'default' | 'chevron' | 'default' | The visual style variant of the accordion item |
tagName | string | 'h3' | HTML tag to use for the title element |
open | boolean | false | Whether the accordion item is initially open |
Accessibility
Accessibility isn’t an afterthought - it’s built into the core of this component through native HTML elements and careful consideration of user interactions. The Accordion component is built with accessibility in mind:
- Uses native HTML
<details>
and<summary>
elements for built-in accessibility - Proper heading structure with configurable heading tags (
h2
-h6
) - Keyboard navigation support:
Enter
orSpace
: Toggle accordion itemTab
: Navigate between focusable elements
- ARIA attributes automatically managed by native elements
- Smooth animations with reduced-motion support
- Automatic light/dark mode color adaptation
- Progressive enhancement using modern CSS features
Styling
Make the Accordion component your own with custom styling while maintaining its accessibility features.
/* Option 1: Using :global() in your style block */<style> :global(.accordion .title) { font-size: 1.5rem; color: var(--sl-color-purple-600); }
:global(.accordion .content) { padding: 2rem; background: light-dark(hsl(204 20% 94%), hsl(215 25% 15%)); }</style>
/* Option 2: Using is:global on the style tag */<style is:global> .accordion .title { font-size: 1.5rem; color: var(--sl-color-purple-600); }
.accordion .content { padding: 2rem; background: light-dark(hsl(204 20% 94%), hsl(215 25% 15%)); }</style>
<Accordion class="border-2 border-dashed border-yellow-400 rounded-lg p-4"> <AccordionItem title="Styled with Tailwind" class="hover:bg-yellow-50 dark:hover:bg-yellow-900" > Content </AccordionItem></Accordion>
Interactive examples
See the Accordion component in action with these practical examples demonstrating different variants and styling options.
Default style
-
What is an Accordion?
An accordion is a vertically stacked set of interactive headings that each reveal a section of content.
Learn more about accordions -
When to use Accordions
Use accordions to organize related content into collapsible sections, making it easier for users to digest information.
-
Accessibility Benefits
Accordions built with native HTML elements provide excellent keyboard navigation and screen reader support out of the box.
-
Best Practices
Keep accordion headers clear and concise. Ensure the content within each panel is relevant to its header.
-
Browser Support
The details and summary elements used in this accordion have excellent browser support across modern browsers.
Chevron style
-
Getting Started
Begin by installing the component library using your package manager of choice.
View installation guide -
Basic Configuration
Configure the accordion component by passing the desired props and styling options.
-
Advanced Usage
Learn about exclusive behavior, custom styling, and advanced interaction patterns.
-
Troubleshooting
Common issues and their solutions when working with the accordion component.
-
API Reference
Complete documentation of all available props, events, and styling options.