Resources
Intro & Anatomy
Accordions organise content into collapsible, vertically stacked sections that users can expand and collapse as needed. Use accordions for secondary information that would otherwise clutter the interface, such as FAQs, specifications, or supplementary content.
Each section contains a clickable header and content area. By default, sections remain collapsed until users interact with headers. When expanded, content becomes accessible whilst other sections stay collapsed, maintaining a clean interface.
MDX offers light and grey variants, both with or without padding for different background contexts.
Options & Styles
Variants
Grey for use on white backgrounds to create visual separation
White for use on coloured backgrounds to maintain contrast
Both variants available with or without padding depending on layout needs
Content
Title/header is mandatory for each accordion section
Content can include text, images, and other non-interactive elements
Rating is optional and displays as static stars only
States
Default and hover states available for both collapsed and expanded sections to provide clear interactive feedback
Accordion Stacks
Accordions are typically displayed in stacked groups for related content organisation. Use either background colour variants or line separators between sections to create clear visual distinction whilst maintaining cohesive grouping.
Best Practice & Usage
Accordions should organise related secondary information whilst maintaining clear visual hierarchy and avoiding content that's essential for task completion.
Accordions commonly present hierarchical content such as FAQs, product descriptions, or categorised information in a space-efficient manner.
Display between 4-12 items for optimal usability without overwhelming users.
Use white accordions on grey backgrounds and vice versa to create visual distinction and grouped content perception.
Avoid using accordions on matching background colours as they lose visual separation.
Cluster related content within accordions so users can easily navigate and find desired information.
Avoid mixing unrelated content in one accordion to prevent user confusion.
Use concise titles that provide quick, understandable content previews.
Avoid lengthy titles that cause text wrapping and create cluttered, confusing interfaces.
Include text and images in expanded content, but keep titles text-only.
Never nest accordions as they're unsupported and create cognitive overload.
Display secondary information that isn't required for task completion.
Never include forms or interactive elements in accordions. Use progressive disclosure patterns instead.
Show only static rating stars without interactive links since the container itself is clickable.
Refrain from using clickable elements inside accordion containers to avoid interaction conflicts.
Set accordions to 100vw or 100% width on mobile devices.
Avoid displaying accordions smaller than full width on mobile.
Theming
You can customise colours, font styles and weights, border width and radius, and spacings to match your design requirements.
When not using MDX icons, a slot is available to use your own icon library or SVG icons.