The accordion component is a vertically stacked set of interactive headings that contain collapsible content sections. Each heading functions as a control that enables users to reveal or hide their associated content. Accordions are essential for organizing information hierarchically and reducing cognitive load by allowing users to focus on relevant content sections.
✅ Use accordions when:
- Organizing content into logical, collapsible sections
- Reducing page length and improving scanability
- Providing progressive disclosure of detailed information
- Creating FAQ sections or help documentation
- Grouping related settings or form sections
❌ Don't use accordions for:
- Primary navigation (use navigation components)
- Critical information that must always be visible
- Content with complex interactions or nested interfaces
- Short content that doesn't benefit from hiding
The most common accordion pattern with simple expand/collapse functionality.
Choose accordion sizes based on content importance and interface density.
Proper heading levels ensure good document structure and accessibility.
Control icon placement and customize expand/collapse indicators.
Accordion states provide important feedback about interaction and content status.
Different accordion variants for various interface contexts.
- Go to the login page and click "Forgot Password"
- Enter your email address
- Check your email for the reset link
- Follow the instructions in the email
Use accordion groups for related content sections with coordinated behavior.
- Valid government-issued ID
- Proof of address (utility bill or bank statement)
- Completed application form
- Supporting documentation (if applicable)
The accordion component supports extensive customization beyond the default variants. This section demonstrates practical styling techniques and advanced customization patterns.
For simple customizations, use CSS custom properties directly on the component:
Create accordions that automatically adapt to different themes:
Experiment with custom styling using CSS parts and custom properties. Try the presets below or create your own styles:
CSS Editor
Live Preview
- Keyboard Navigation: Space/Enter keys expand/collapse, Tab navigates between accordions
- Screen Reader Support: Proper ARIA attributes announce state changes and content relationships
- Heading Structure: Use appropriate heading levels to maintain document hierarchy
- Focus Management: Clear focus indicators and logical tab order
- State Announcements: Loading and disabled states are properly communicated
- Space/Enter: Toggles the accordion open/closed state
- Tab: Moves focus between accordion buttons
- Disabled accordions: Are skipped in tab order and don't respond to interaction
- Accordion buttons announce their expanded/collapsed state
- Content regions are properly labeled and associated with their headings
- Loading states announce status to assistive technology
- Heading levels create logical document structure
import { DapDSAccordion } from 'dap-design-system'
import { DapDSAccordionReact } from 'dap-design-system/react'
For optimal bundle sizes, use the tree-shakeable import syntax:
import { DapDSAccordion } from 'dap-design-system/components'
| Property | Type | Default | Description |
|---|---|---|---|
size | 'xxs', 'xs' , 'sm' , 'md' , 'lg' | The size of the accordion. Default is sm. Visual variants are sm and lg (other sizes map to sm). | |
sizeMap | string | Responsive size map (e.g. "md:lg") | |
parentSized | string | When "true", size is taken from the parent card if present. | |
heading | string | The heading text of the accordion, this will be used as the aria label of the heading also if ariaLabel is not provided | |
headingLevel | 1, 2 , 3 , 4 , 5 , 6 | The heading level of the accordion. Default is 4. | |
opened | boolean | Whether the accordion is opened. Default is false. | |
iconLocation | 'left', 'right' | The location of the icon. Default is right. | |
variant | 'default', 'collapsed' , 'clean' , 'clean-collapsed' | The variant of the accordion. | |
lastItem | boolean | Whether the accordion is the last item. | |
disabled | boolean | Whether the accordion is disabled. | |
loading | boolean | Whether the accordion is in loading state. |
| Name | Description |
|---|---|
default | The content of the accordion. |
heading | The heading of the accordion. |
icon-opened | The icon when the accordion is opened. |
icon-closed | The icon when the accordion is closed. |
| Event Name | Description | Type |
|---|---|---|
dds-opened | Event fired when the accordion is opened. | {open: boolean, item: AccordionBaseElement } |
dds-closed | Event fired when the accordion is closed. | {open: boolean, item: AccordionBaseElement } |
| Part Name | Description |
|---|---|
base | The main accordion container. |
heading | The heading of the accordion. |
button | The button of the accordion. |
content | The content of the accordion. |
content-container | The container of the accordion content. |
icon-wrapper | The icon wrapper of the accordion. |
open-icon | The icon when the accordion is opened. |
open-icon-base | The base of the icon when the accordion is opened. |
close-icon | The icon when the accordion is closed. |
close-icon-base | The base of the icon when the accordion is closed. |
You can style CSS parts using the ::part() pseudo-element selector:
/* Target a specific part */
.my-custom-dap-ds-accordion::part(base) {
/* Your custom styles */
}
/* Target multiple parts */
.my-custom-dap-ds-accordion::part(base),
.my-custom-dap-ds-accordion::part(heading) {
/* Shared styles */
}
Example usage:
<dap-ds-accordion class="my-custom-dap-ds-accordion">
Accordion
</dap-ds-accordion>
.my-custom-dap-ds-accordion::part(base) {
border-radius: 12px;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}
CSS parts allow you to style internal elements of the component while maintaining encapsulation. Learn more in our styling guide.
| Property Name | Description |
|---|---|
--dds-accordion-border-width | The width of the accordion border (default: var(--dds-border-width-base)) |
--dds-accordion-border-style | The style of the accordion border (default: solid) |
--dds-accordion-border-radius | The border radius of the accordion (default: var(--dds-radius-base)) |
--dds-accordion-border-color | The color of the accordion border (default: var(--dds-border-neutral-divider)) |
--dds-accordion-background-color | The background color of the accordion (default: var(--dds-background-neutral-subtle)) |
--dds-accordion-text-color | The text color of the accordion (default: var(--dds-text-neutral-strong)) |
--dds-accordion-hover-background | The background color when hovering over the accordion (default: var(--dds-background-neutral-base)) |
--dds-accordion-active-background | The background color when the accordion is active (default: var(--dds-background-neutral-medium)) |
--dds-accordion-icon-background | The background color of the accordion icon (default: var(--dds-transparent-black-subtle)) |
--dds-accordion-icon-color | The color of the accordion icon (default: var(--dds-icon-neutral-base)) |
--dds-accordion-icon-hover-background | The background color of the accordion icon when hovered (default: var(--dds-transparent-black-base)) |
--dds-accordion-icon-active-background | The background color of the accordion icon when active (default: var(--dds-transparent-black-strong)) |
--dds-accordion-icon-hover-color | The color of the accordion icon when hovered (default: var(--dds-icon-neutral-strong)) |
--dds-accordion-icon-active-color | The color of the accordion icon when active (default: var(--dds-icon-neutral-strong)) |
--dds-accordion-content-color | The color of the accordion content (default: var(--dds-text-text-neutral)) |
--dds-accordion-transition-duration | The duration of the accordion transitions (default: var(--dds-transition-fast)) |
--dds-accordion-transition-timing | The timing function of the accordion transitions (default: var(--dds-easing-ease-in-out)) |
--dds-accordion-divider-color | The color of the divider between accordion items (default: var(--dds-border-neutral-divider)) |
CSS custom properties (CSS variables) can be set directly on the component or in your stylesheet:
Method 1: Inline styles (Quick customization)
<dap-ds-accordion
style="--dds-accordion-border-width: value; --dds-accordion-border-style: value;">
Accordion
</dap-ds-accordion>
Method 2: CSS classes (Reusable styles)
.my-custom-dap-ds-accordion {
--dds-accordion-border-width: value;
--dds-accordion-border-style: value;
--dds-accordion-border-radius: value;
}
<dap-ds-accordion class="my-custom-dap-ds-accordion">
Accordion
</dap-ds-accordion>
Method 3: Global theme customization
/* Apply to all instances */
dap-ds-accordion {
--dds-accordion-border-width: value;
--dds-accordion-border-style: value;
}
CSS custom properties inherit through the Shadow DOM, making them perfect for theming. Changes apply immediately without rebuilding.
| Property | Type | Default | Description |
|---|---|---|---|
autoClose | string | 'true' | Whether to close other accordions when one is opened. |
variant | 'default', 'collapsed' , 'clean' , 'clean-collapsed' | 'default' | The variant of the accordion |
| Name | Description |
|---|---|
(default) | The content of the accordion group. |
No custom events available.
| Part Name | Description |
|---|---|
base | The main accordion group container. |
| Property Name | Description |
|---|---|
--dds-accordion-group-spacing | Controls the gap between accordion items (default: var(--dds-spacing-300)) |
--dds-accordion-group-border-color | Controls the border color (default: var(--dds-border-neutral-subtle)) |
--dds-accordion-group-border-width | Controls the border width (default: var(--dds-border-width-base)) |
--dds-accordion-group-border-radius | Controls the border radius (default: var(--dds-radius-base)) |
--dds-accordion-group-background | Controls the background color (default: transparent) |
