Skip to content

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

PropTypeDefaultDescription
classstring''Additional CSS classes to apply to the accordion wrapper

AccordionItem

PropTypeDefaultDescription
namestring''Optional group name for exclusive opening behavior
titlestringrequiredThe header text for the accordion item
classstring''Additional CSS classes to apply to the item
variant'default' | 'chevron''default'The visual style variant of the accordion item
tagNamestring'h3'HTML tag to use for the title element
openbooleanfalseWhether 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 or Space: Toggle accordion item
    • Tab: 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>

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.