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.
Design system docsWhen to Use
✅ 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
ExamplesBasic Usage
The most common accordion pattern with simple expand/collapse functionality.
<dap-ds-stack><dap-ds-accordion><spanslot="heading">Getting Started</span><dap-ds-typographyvariant="body"> This section contains the basic information you need to begin using our services. Follow the steps outlined here to set up your account and configure your preferences.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionopened><spanslot="heading">Account Settings</span><dap-ds-typographyvariant="body"> Manage your personal information, notification preferences, and privacy settings. You can update these settings at any time from your dashboard.</dap-ds-typography></dap-ds-accordion></dap-ds-stack>
Sizes & Visual Hierarchy
Choose accordion sizes based on content importance and interface density.
<dap-ds-stack><div><dap-ds-typographyvariant="h4">Small accordion (default)</dap-ds-typography><dap-ds-accordionsize="sm"><spanslot="heading">Compact Information</span><dap-ds-typographyvariant="body"> Use small accordions for secondary information or in dense interfaces where space is at a premium.</dap-ds-typography></dap-ds-accordion></div><div><dap-ds-typographyvariant="h4">Large accordion</dap-ds-typography><dap-ds-accordionsize="lg"><spanslot="heading">Important Information</span><dap-ds-typographyvariant="body"> Use large accordions for primary content sections or when you need more visual prominence for important information.</dap-ds-typography></dap-ds-accordion></div></dap-ds-stack>
Heading Levels & Semantic Structure
Proper heading levels ensure good document structure and accessibility.
<dap-ds-stack><dap-ds-typographyvariant="h2">Document Sections</dap-ds-typography><dap-ds-accordionheadingLevel="3"><spanslot="heading">Section 1: Overview</span><dap-ds-typographyvariant="body"> This is a top-level section with heading level 3, appropriate for main content areas.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionheadingLevel="4"><spanslot="heading">Subsection 1.1: Details</span><dap-ds-typographyvariant="body"> This is a subsection with heading level 4, showing hierarchical content organization.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionheadingLevel="4"><spanslot="heading">Subsection 1.2: Examples</span><dap-ds-typographyvariant="body"> Another subsection at the same level, maintaining proper document structure.</dap-ds-typography></dap-ds-accordion></dap-ds-stack>
Icon Positioning & Customization
Control icon placement and customize expand/collapse indicators.
<dap-ds-stack><div><dap-ds-typographyvariant="h4">Icon positioning</dap-ds-typography><dap-ds-stack><dap-ds-accordioniconLocation="right"><spanslot="heading">Icon on the right (default)</span><dap-ds-typographyvariant="body"> The default icon placement follows common UI patterns.</dap-ds-typography></dap-ds-accordion><dap-ds-accordioniconLocation="left"><spanslot="heading">Icon on the left</span><dap-ds-typographyvariant="body"> Left-aligned icons can work better in some layout contexts.</dap-ds-typography></dap-ds-accordion></dap-ds-stack></div><div><dap-ds-typographyvariant="h4">Custom icons</dap-ds-typography><dap-ds-accordion><spanslot="icon-closed"><dap-ds-iconname="document-folder-line"size="16"></dap-ds-icon></span><spanslot="icon-opened"><dap-ds-iconname="document-folder-open-line"size="16"></dap-ds-icon></span><spanslot="heading">Custom Folder Icons</span><dap-ds-typographyvariant="body"> You can customize both the closed and opened state icons to match your content theme.</dap-ds-typography></dap-ds-accordion></div></dap-ds-stack>
States & Feedback
Accordion states provide important feedback about interaction and content status.
<dap-ds-stack><div><dap-ds-typographyvariant="h4">Interactive states</dap-ds-typography><dap-ds-stack><dap-ds-accordion><spanslot="heading">Normal State</span><dap-ds-typographyvariant="body"> Standard accordion behavior with normal interaction.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionloading><spanslot="heading">Loading Content</span><dap-ds-typographyvariant="body"> Shows loading state when content is being fetched asynchronously.</dap-ds-typography></dap-ds-accordion><dap-ds-accordiondisabled><spanslot="heading">Disabled Section</span><dap-ds-typographyvariant="body"> Content that is temporarily unavailable or restricted.</dap-ds-typography></dap-ds-accordion></dap-ds-stack></div></dap-ds-stack>
Variants & Styling
Different accordion variants for various interface contexts.
<dap-ds-stack><div><dap-ds-typographyvariant="h4">Default variant</dap-ds-typography><dap-ds-accordionvariant="default"><spanslot="heading">Standard Accordion</span><dap-ds-typographyvariant="body"> The default accordion style with standard borders and spacing.</dap-ds-typography></dap-ds-accordion></div><div><dap-ds-typographyvariant="h4">Clean variant</dap-ds-typography><dap-ds-accordionvariant="clean"><spanslot="heading">Clean Accordion</span><dap-ds-typographyvariant="body"> A minimal style without borders, suitable for content-focused layouts.</dap-ds-typography></dap-ds-accordion></div><div><dap-ds-typographyvariant="h4">Collapsed variant</dap-ds-typography><dap-ds-accordion-groupvariant="collapsed"><dap-ds-accordion><spanslot="heading">Collapsed Style</span><dap-ds-typographyvariant="body"> Optimized for grouped accordions with connected visual appearance.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionvariant="collapsed"><spanslot="heading">Collapsed Style</span><dap-ds-typographyvariant="body"> Optimized for grouped accordions with connected visual appearance.</dap-ds-typography></dap-ds-accordion></dap-ds-accordion-group></div></dap-ds-stack>
Real-World PatternsFAQ Section
<divstyle={{border:'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding:'var(--dds-spacing-600)', borderRadius:'var(--dds-radius-base)'}}><dap-ds-stack><dap-ds-typographyvariant="h3">Frequently Asked Questions</dap-ds-typography><dap-ds-accordionheadingLevel="4"><spanslot="heading">How do I reset my password?</span><dap-ds-stack><dap-ds-typographyvariant="body"> To reset your password, follow these steps:</dap-ds-typography><olstyle={{paddingLeft:'var(--dds-spacing-400)'}}><li>Go to the login page and click "Forgot Password"</li><li>Enter your email address</li><li>Check your email for the reset link</li><li>Follow the instructions in the email</li></ol></dap-ds-stack></dap-ds-accordion><dap-ds-accordionheadingLevel="4"><spanslot="heading">How long does document processing take?</span><dap-ds-typographyvariant="body"> Document processing typically takes 2-5 business days. You'll receive an email notification when your document is ready for review. For urgent requests, please contact our support team.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionheadingLevel="4"><spanslot="heading">Can I update my application after submission?</span><dap-ds-typographyvariant="body"> Yes, you can update your application within 24 hours of submission. After this period, you'll need to contact our office directly to make changes.</dap-ds-typography></dap-ds-accordion></dap-ds-stack></div>
Use accordion groups for related content sections with coordinated behavior.
<divstyle={{border:'var(--dds-border-width-base) solid var(--dds-border-neutral-subtle)', padding:'var(--dds-spacing-600)', borderRadius:'var(--dds-radius-base)'}}><dap-ds-stack><dap-ds-typographyvariant="h3">Service Information</dap-ds-typography><dap-ds-accordion-group><dap-ds-accordionheadingLevel="4"><spanslot="heading">Eligibility Requirements</span><dap-ds-typographyvariant="body"> To be eligible for this service, you must be a Hungarian citizen or permanent resident, over 18 years of age, and have a valid identification document.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionheadingLevel="4"><spanslot="heading">Required Documents</span><dap-ds-stack><dap-ds-typographyvariant="body">Please prepare the following documents:</dap-ds-typography><ulstyle={{paddingLeft:'var(--dds-spacing-400)'}}><li>Valid government-issued ID</li><li>Proof of address (utility bill or bank statement)</li><li>Completed application form</li><li>Supporting documentation (if applicable)</li></ul></dap-ds-stack></dap-ds-accordion><dap-ds-accordionheadingLevel="4"><spanslot="heading">Processing Time</span><dap-ds-typographyvariant="body"> Standard processing time is 5-10 business days. Express processing is available for an additional fee and reduces processing time to 1-2 business days.</dap-ds-typography></dap-ds-accordion></dap-ds-accordion-group></dap-ds-stack></div>
Custom Styling
The accordion component supports extensive customization beyond the default variants. This section demonstrates practical styling techniques and advanced customization patterns.
Quick Customization with Inline Styles
For simple customizations, use CSS custom properties directly on the component:
<dap-ds-stackdirection="column"><dap-ds-accordionstyle={{'--dds-accordion-border-color':'var(--dds-violet-600)','--dds-accordion-border-width':'2px','--dds-accordion-border-radius':'var(--dds-radius-large)','--dds-accordion-background-color':'var(--dds-violet-100)',}}><spanslot="heading">Custom Purple Accent</span><dap-ds-typographyvariant="body"> This accordion uses custom purple styling with enhanced borders and background.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionstyle={{'--dds-accordion-icon-color':'var(--dds-teal-700)','--dds-accordion-icon-background':'var(--dds-teal-100)','--dds-accordion-hover-background':'var(--dds-teal-50)',}}><spanslot="heading">Custom Teal Icons</span><dap-ds-typographyvariant="body"> This accordion features custom teal icons and hover effects with rounded corners.</dap-ds-typography></dap-ds-accordion></dap-ds-stack>
Theme-Aware Styling
Create accordions that automatically adapt to different themes:
<dap-ds-stackdirection="column"><dap-ds-accordionstyle={{'--dds-accordion-background-color':'var(--dds-brand-100)','--dds-accordion-border-color':'var(--dds-brand-600)','--dds-accordion-text-color':'var(--dds-brand-1000)','--dds-accordion-icon-color':'var(--dds-brand-800)',}}><spanslot="heading">Brand Themed</span><dap-ds-typographyvariant="body"> This accordion uses brand colors that adapt automatically to theme changes.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionstyle={{'--dds-accordion-background-color':'var(--dds-informative-100)','--dds-accordion-border-color':'var(--dds-informative-500)','--dds-accordion-hover-background':'var(--dds-informative-200)','--dds-accordion-icon-background':'var(--dds-informative-300)',}}><spanslot="heading">Informative Style</span><dap-ds-typographyvariant="body"> This accordion uses informative semantic colors for status indication.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionstyle={{'--dds-accordion-background-color':'var(--dds-positive-100)','--dds-accordion-border-color':'var(--dds-positive-600)','--dds-accordion-text-color':'var(--dds-positive-900)','--dds-accordion-divider-color':'var(--dds-positive-300)',}}><spanslot="heading">Success Styling</span><dap-ds-typographyvariant="body"> This accordion uses positive colors to indicate successful completion or confirmation.</dap-ds-typography></dap-ds-accordion></dap-ds-stack>
Advanced CSS Classes
For reusable styling patterns, define CSS classes in your stylesheet:
<dap-ds-stack><dap-ds-accordionclass="card-accordion"><spanslot="heading">Card-style Accordion</span><dap-ds-typographyvariant="body"> This accordion uses a card-style design with a shadow and rounded corners.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionclass="minimal-accordion"><spanslot="heading">Minimal Accordion</span><dap-ds-typographyvariant="body"> This accordion has no borders and uses a subtle hover effect.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionclass="warning-accordion"><spanslot="heading">Warning Accordion</span><dap-ds-typographyvariant="body"> This accordion uses a warning color for status indication.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionclass="error-accordion"><spanslot="heading">Error Accordion</span><dap-ds-typographyvariant="body"> This accordion uses an error color for status indication.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionclass="compact-accordion"><spanslot="heading">Compact Accordion</span><dap-ds-typographyvariant="body"> This accordion uses a compact design for dense layouts.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionclass="gradient-accordion"><spanslot="heading">Gradient Accordion</span><dap-ds-typographyvariant="body"> This accordion uses a gradient background for a modern look.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionclass="enhanced-accordion"><spanslot="heading">Enhanced Accordion</span><dap-ds-typographyvariant="body"> This accordion uses enhanced focus and interaction states.</dap-ds-typography></dap-ds-accordion></dap-ds-stack>
/* Card-style accordion with shadow */.card-accordion{--dds-accordion-background-color:var(--dds-white-100);--dds-accordion-border-color:var(--dds-neutral-300);--dds-accordion-border-radius:var(--dds-radius-large);--dds-accordion-border-width:1px;margin-bottom:var(--dds-spacing-400);}/* Minimal accordion without borders */.minimal-accordion{--dds-accordion-border-color:transparent;--dds-accordion-background-color:transparent;--dds-accordion-hover-background:var(--dds-neutral-100);--dds-accordion-divider-color:var(--dds-neutral-200);}/* Status-specific accordion styling */.warning-accordion{--dds-accordion-background-color:var(--dds-warning-100);--dds-accordion-border-color:var(--dds-warning-500);--dds-accordion-text-color:var(--dds-warning-900);--dds-accordion-icon-color:var(--dds-warning-700);--dds-accordion-hover-background:var(--dds-warning-200);}.error-accordion{--dds-accordion-background-color:var(--dds-negative-100);--dds-accordion-border-color:var(--dds-negative-500);--dds-accordion-text-color:var(--dds-negative-900);--dds-accordion-icon-color:var(--dds-negative-700);}/* Compact accordion for dense layouts */.compact-accordion{--dds-accordion-padding:var(--dds-spacing-300);--dds-accordion-border-radius:var(--dds-radius-small);--dds-accordion-transition-duration:0.15s;}/* Gradient background effect */.gradient-accordion::part(header){background:linear-gradient(135deg,var(--dds-brand-100),var(--dds-violet-100));background-size:200%200%;animation: gradient-shift 4s ease infinite;}@keyframes gradient-shift{0%{background-position:0%50%;}50%{background-position:100%50%;}100%{background-position:0%50%;}}/* Enhanced focus and interaction states */.enhanced-accordion::part(button):focus{box-shadow:0002pxvar(--dds-focus-outer-ring),0004pxvar(--dds-focus-inner-ring);outline: none;}.enhanced-accordion::part(button):hover{transform:translateY(-1px);box-shadow:02px8pxrgba(0,0,0,0.1);transition: all 0.2s ease;}/* Custom icon styling */.custom-icon-accordion::part(icon){border-radius:50%;padding:var(--dds-spacing-100);transition: all 0.3s ease;}.custom-icon-accordion::part(icon):hover{transform:scale(1.1);box-shadow:02px4pxrgba(0,0,0,0.1);}/* Content area styling */.styled-content-accordion::part(content){border-left:3px solid var(--dds-brand-500);padding-left:var(--dds-spacing-600);margin-left:var(--dds-spacing-400);background:var(--dds-brand-50);}
AccessibilityRequirements
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
Keyboard Navigation
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
Screen Reader Support
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
<dap-ds-stack><dap-ds-typographyvariant="h4">Good accessibility examples:</dap-ds-typography><dap-ds-accordionheadingLevel="3"aria-label="Customer support information"aria-describedby="support-description"><spanslot="heading">Customer Support</span><divid="support-description"><dap-ds-typographyvariant="body"> Contact information and hours for customer support services. Available 24/7 for urgent matters, regular hours Monday-Friday 9AM-5PM.</dap-ds-typography></div></dap-ds-accordion><dap-ds-accordionheadingLevel="3"loading><spanslot="heading">Loading Content Section</span><dap-ds-typographyvariant="body"> This section demonstrates proper loading state announcements.</dap-ds-typography></dap-ds-accordion><dap-ds-accordionheadingLevel="3"disabled><spanslot="heading">Restricted Access</span><dap-ds-typographyvariant="body"> This content is currently unavailable due to access restrictions.</dap-ds-typography></dap-ds-accordion></dap-ds-stack>