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>

Exclusive behavior

Use the name prop to create mutually exclusive accordion groups where only one item can be open at a time. Leave it empty to allow multiple items to be open at the same time.

Initial state

Use the open prop to set an accordion item’s initial state. This is particularly useful for FAQ sections where you want to highlight the most common question.

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 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

User preferences

The component automatically respects user preferences for reduced motion and color scheme.

Styling

Make the Accordion component your own with custom styling while maintaining its accessibility features.

Accessibility considerations

When applying custom styles, ensure they don’t compromise accessibility by regularly testing your changes with manual and automated accessibility audits.

Custom CSS

/* 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>

Tailwind Classes

<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>

Style scoping

Astro components use scoped styles by default. To override component styles, you’ll need to use either :global() selectors or the is:global directive on your style tag.

Interactive examples

See the Accordion component in action with these practical examples demonstrating different variants and styling options.

Default style

Exclusive behavior

This example demonstrates the exclusive behavior of the accordion component. Only one item can be open at a time.

• 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.