Accordion - National Design System

Added in v1.0.0 Updated in v1.4.0

Collapsible content panels for organizing information in a space-efficient manner

Standard

Basic collapsible panels with toggle controls for size, card view, and always-open mode

Overview of the service and how to begin your application.

Documents and eligibility criteria needed before applying.

Fee schedule and expected processing times.


<div class="nds-accordion nds-lg" id="my-accordion">
    <div class="nds-accordion-item">
        <h3 class="nds-accordion-header" id="heading-1">
            <button class="nds-btn nds-subtle nds-menu-btn nds-accordion-btn" type="button"
                aria-expanded="true" data-state="open" aria-controls="collapse-1">
                <span class="nds-accordion-title">Getting Started</span>
            </button>
        </h3>
        <div class="nds-accordion-collapse" id="collapse-1" data-state="open">
            <div class="nds-accordion-content">
                <div class="nds-accordion-body">
                    <p>Overview of the service and how to begin.</p>
                </div>
            </div>
        </div>
    </div>
    <div class="nds-accordion-item">
        <h3 class="nds-accordion-header" id="heading-2">
            <button class="nds-btn nds-subtle nds-menu-btn nds-accordion-btn" type="button"
                aria-expanded="false" aria-controls="collapse-2">
                <span class="nds-accordion-title">Requirements</span>
            </button>
        </h3>
        <div class="nds-accordion-collapse" id="collapse-2">
            <div class="nds-accordion-content">
                <div class="nds-accordion-body">
                    <p>Documents and eligibility criteria needed.</p>
                </div>
            </div>
        </div>
    </div>
    <div class="nds-accordion-item">
        <h3 class="nds-accordion-header" id="heading-3">
            <button class="nds-btn nds-subtle nds-menu-btn nds-accordion-btn" type="button"
                aria-expanded="false" aria-controls="collapse-3">
                <span class="nds-accordion-title">Fees & Processing</span>
            </button>
        </h3>
        <div class="nds-accordion-collapse" id="collapse-3">
            <div class="nds-accordion-content">
                <div class="nds-accordion-body">
                    <p>Fee schedule and expected processing times.</p>
                </div>
            </div>
        </div>
    </div>
</div>

With Leading Icons

Add icons before each title for visual context and faster scanning

Browse housing programs and check eligibility.

Scholarships, transcripts, and certification exams.

Registration renewal, fines, and driving tests.


<div class="nds-accordion nds-lg" id="icon-accordion">
    <div class="nds-accordion-item">
        <h3 class="nds-accordion-header" id="icon-heading-1">
            <button class="nds-btn nds-subtle nds-menu-btn nds-accordion-btn" type="button"
                aria-expanded="true" aria-controls="icon-collapse-1">
                <i class="hgi hgi-stroke hgi-home-01 nds-accordion-leading-icon"></i>
                <span class="nds-accordion-title">Housing</span>
            </button>
        </h3>
        <div class="nds-accordion-collapse" id="icon-collapse-1">
            <div class="nds-accordion-content">
                <div class="nds-accordion-body">
                    <p>Browse housing programs and check eligibility.</p>
                </div>
            </div>
        </div>
    </div>
    <div class="nds-accordion-item">
        <h3 class="nds-accordion-header" id="icon-heading-2">
            <button class="nds-btn nds-subtle nds-menu-btn nds-accordion-btn" type="button"
                aria-expanded="false" aria-controls="icon-collapse-2">
                <i class="hgi hgi-stroke hgi-graduation-scroll nds-accordion-leading-icon"></i>
                <span class="nds-accordion-title">Education</span>
            </button>
        </h3>
        <div class="nds-accordion-collapse" id="icon-collapse-2">
            <div class="nds-accordion-content">
                <div class="nds-accordion-body">
                    <p>Scholarships, transcripts, and certification exams.</p>
                </div>
            </div>
        </div>
    </div>
    <div class="nds-accordion-item">
        <h3 class="nds-accordion-header" id="icon-heading-3">
            <button class="nds-btn nds-subtle nds-menu-btn nds-accordion-btn" type="button"
                aria-expanded="false" aria-controls="icon-collapse-3">
                <i class="hgi hgi-stroke hgi-car-01 nds-accordion-leading-icon"></i>
                <span class="nds-accordion-title">Vehicles</span>
            </button>
        </h3>
        <div class="nds-accordion-collapse" id="icon-collapse-3">
            <div class="nds-accordion-content">
                <div class="nds-accordion-body">
                    <p>Registration renewal, fines, and driving tests.</p>
                </div>
            </div>
        </div>
    </div>
</div>

Built-in Features

Auto-initialization

Activates when .nds-accordion is on the page. No JavaScript setup required.

Smooth Animations

CSS grid transitions with automatic fallback when users prefer reduced motion.

Keyboard Navigation

Arrow keys, Home, End, Enter, and Space for full keyboard control.

JavaScript API

Public API to open, close, and toggle items. Custom events fire on state change for analytics or dependent UI.

Print-ready

All panels expand automatically so no content is hidden on paper.

Accessibility

High contrast and screen reader support built into every state.

Usage Guidelines

Modifier Classes

Class	Applies to	Description
`nds-lg`	`.nds-accordion`	Large size: 56px header height, `--spacing-xl` padding (default)
`nds-md`	`.nds-accordion`	Medium size: 48px header height, `--spacing-lg` padding
`nds-sm`	`.nds-accordion`	Small size: 40px header height, `--spacing-md` padding
`nds-card`	`.nds-accordion`	Card container view: collapses outer border and uses card gap. Combine with `nds-stroke` and `nds-shadow` for the full card look
`nds-stroke`	`.nds-accordion.nds-card`	Adds an outer border to the card container
`nds-shadow`	`.nds-accordion.nds-card`	Adds elevation shadow to the card container

Data Attributes

Attribute	Applies to	Description
`data-state="always-open"`	`.nds-accordion`	Allows multiple panels to be open at the same time. Without it, opening one panel closes the others
`data-state="open"`	`.nds-accordion-btn` and `.nds-accordion-collapse`	Server-rendered initial open state. Set on both the button and its collapse panel to expand a panel before JS initializes, preventing a 0fr animation on load
`data-nds-accordion-initialized`	`.nds-accordion`	Stamped by JS after initialization. Enables collapse transitions and removes the skeleton loading state. Do not set this manually

CSS Custom Properties

Property	Default	Description
`--accordion-header-height`	`56px`	Height of each accordion button. Overridden per size class (`nds-lg/md/sm`). Set inline on `.nds-accordion` to customize a single instance
`--accordion-header-padding`	`--spacing-xl`	Inline padding of the accordion button. Overridden per size class. Set inline on `.nds-accordion` to customize a single instance

Loading and Skeleton State

The accordion shows a shimmer skeleton on its items in three situations: before JS initializes (:not([data-nds-accordion-initialized])), when explicitly set to loading (nds-loading class or data-state="loading"), and when it is a filter target waiting for the filter to apply URL params (data-filter-items without data-nds-filter-initialized). Titles, leading icons, and open body content all animate as skeleton bars. Collapse transitions are suppressed until the init stamp lands so the initial open state paints without a 0fr transition.

When to Use

Use accordions to progressively disclose content. Show headings first, let users expand what they need
Good for FAQs, categorized service lists, and settings panels where users scan then drill down
Avoid accordions for content users need to compare side-by-side. Use tabs or a flat layout instead
Keep accordion titles short and scannable. Users decide whether to expand based on the title alone

JavaScript API

The NDS.Accordion API provides methods to create instances, control panels programmatically, and listen for state changes. For dynamically added accordions, call NDS.Accordion.reinit() to initialize new elements.


// Re-scan the page and initialize any new accordions
NDS.Accordion.init();

// Shorthand for init(), use after adding dynamic content
NDS.Accordion.reinit();

// Create and return an instance for a specific element
const instance = NDS.Accordion.create(document.querySelector('#my-accordion'));

// Instance methods
instance.openItem(0);       // Open first item
instance.closeItem(1);      // Close second item
instance.toggleItem(2);     // Toggle third item
instance.closeAll();        // Close all items

// Get currently open items
const openItems = instance.getOpenItems();
// Returns: [{index, button, collapse, isOpen}, ...]

// Access an existing instance from a DOM element
const existing = document.querySelector('#my-accordion').ndsAccordion;

// Clean up when removing an accordion from the DOM
instance.destroy();

// Custom events (both bubble, same detail shape)
document.addEventListener('nds:accordion:shown', (e) => {
    // e.detail: {index, button, collapse, accordion}
    console.log('Opened item:', e.detail.index);
});

document.addEventListener('nds:accordion:hidden', (e) => {
    console.log('Closed item:', e.detail.index);
});

Last Modified Date: 28/06/2026 - 01:27 PM