How to Implement a Simple Accordion with CSS and JS

In late 2022, the popular news aggregator "InfoStream.net" faced a barrage of user complaints. Its mobile experience, once praised for its speed, had become sluggish, particularly when users tried to expand article summaries or comment sections. An internal audit, later detailed in a company blog post, pointed directly to an updated UI library. This library, while offering a suite of "easy-to-implement" components, inadvertently ballooned the site's JavaScript bundle by over 200KB and introduced a frustrating 450ms delay in content expansion. The culprit? A seemingly innocuous accordion component, pulling in far more code than it needed. This isn't an isolated incident; it's a widespread issue hiding in plain sight. Here's the thing: many developers are over-engineering one of the web's most fundamental UI elements.

The Hidden Cost of "Simple" Frameworks: Why Less Is More

Developers often gravitate towards pre-built UI frameworks like Bootstrap, Material UI, or even React/Vue component libraries for components like an accordion. It's understandable; they promise quick integration and consistent styling. But this perceived simplicity often masks a significant underlying complexity and performance penalty. For instance, the accordion component in Bootstrap 5, while not dependent on jQuery anymore, still requires the full Bootstrap JavaScript bundle, which itself is a substantial file. If you're only using the accordion, you're loading dozens of kilobytes of code for carousels, modals, and tooltips you don't need. This isn't just theoretical. A 2022 analysis by the HTTP Archive's Web Almanac reported that the median mobile page transfers 430 KB of JavaScript, a figure that continues to climb. A significant portion of this is often unused code from large frameworks. This bloat directly impacts user experience. A 2023 study by Portent revealed that a 1-second delay in mobile page load time can lead to a 20% drop in conversion rates for e-commerce sites. Your "simple" accordion, if it's contributing to that delay, isn't simple at all; it's a business liability. We're talking about real money, real users, and real frustration. Why pay that price when a leaner, more efficient solution is within reach?

Deciphering the Performance Penalty

Every additional kilobyte of JavaScript takes time to download, parse, and execute. For users on slower networks or less powerful devices, this delay is amplified. Imagine a user in a rural area trying to access your site on an older smartphone. A heavy JavaScript bundle, even for a single accordion, can make the difference between a usable experience and a frustrated bounce. Google's Lighthouse auditing tool frequently flags "reduce unused JavaScript" as a critical performance recommendation, and heavy framework usage for basic UI elements is a prime offender. By opting for vanilla CSS and JS, you gain granular control, ensuring only the necessary bytes are delivered to the browser.

The Accessibility Trapdoor

Beyond performance, frameworks often present an accessibility challenge. While many popular libraries strive for WCAG compliance, their default implementations aren't always perfect, and customization can inadvertently break crucial accessibility features. Developers might assume the framework handles everything, neglecting to test with screen readers or keyboard navigation. This leads to a common scenario where a visually perfect accordion is completely unusable for someone relying on assistive technologies. Ensuring an accessible experience from the ground up, with semantic HTML and appropriate ARIA attributes, is far easier than retrofitting a complex, pre-built component.

Deconstructing the Accordion: Core HTML Structure for Accessibility

The foundation of any robust web component is its HTML. For an accordion, we're aiming for semantic clarity and inherent accessibility. Forget `div` soup; we want elements that convey meaning to both browsers and assistive technologies. The `details` and `summary` elements offer a native, HTML-only accordion solution, which is fantastic for its simplicity. However, to demonstrate full control with CSS and JS, we'll build a custom structure using `div` elements, ensuring we implement all necessary ARIA attributes. This gives us the flexibility to extend its functionality precisely. Our structure will consist of a container for the entire accordion, and then individual items, each with a button (the summary/title) and a content panel. The button will toggle the visibility of its associated panel. Here’s the basic HTML structure we'll use:

  

    

      
        What is a simple accordion?
      
    
    
  

  

    

      
        Why use vanilla CSS and JS?
      
    
    
  

Notice the critical ARIA attributes: `aria-expanded="false"` (initially collapsed) on the button, `aria-controls` pointing to the associated content panel, and `aria-labelledby` on the panel pointing back to its button. The `role="region"` for the panel helps screen readers understand its purpose. The `hidden` attribute on the panel ensures it's not discoverable by assistive technologies when collapsed, and it also provides a default visual hiding mechanism that our CSS will override. The W3C's ARIA Authoring Practices Guide 1.2, published in 2019, explicitly recommends these attributes for accordions to ensure maximum compatibility with screen readers like JAWS, NVDA, and VoiceOver. Sites like gov.uk, known for their rigorous accessibility standards, implement similar structures for their collapsible content sections.

Styling with CSS: Visuals, Transitions, and Theming

With our semantic HTML in place, CSS brings our accordion to life, adding visual appeal and smooth transitions without requiring any JavaScript. The goal is a clean, functional design that's easy to customize. We'll start with basic styling for the accordion container, items, and especially the trigger buttons and content panels.

.accordion-item {
  border: 1px solid var(--accordion-border-color, #ccc);
  margin-bottom: 10px;
  border-radius: 4px;
  overflow: hidden; /* Crucial for transition */
}

.accordion-trigger {
  display: flex;
  justify-content: space-between;
  align-items: center;
  width: 100%;
  padding: 15px 20px;
  background-color: var(--accordion-header-bg, #f7f7f7);
  border: none;
  text-align: left;
  font-size: 1.1em;
  cursor: pointer;
  font-weight: bold;
  color: var(--accordion-header-color, #333);
  transition: background-color 0.2s ease, color 0.2s ease;
}

.accordion-trigger:hover,
.accordion-trigger:focus {
  background-color: var(--accordion-header-hover-bg, #e9e9e9);
  outline: none;
}

.accordion-trigger[aria-expanded="true"] {
  background-color: var(--accordion-header-active-bg, #e0e0e0);
  color: var(--accordion-header-active-color, #222);
}

.accordion-panel {
  max-height: 0; /* Initial collapsed state for transition */
  opacity: 0;
  visibility: hidden;
  transition: max-height 0.3s ease-out, opacity 0.3s ease-out, visibility 0.3s ease-out;
  padding: 0 20px; /* Padding for when it's visible */
}

.accordion-panel.is-expanded {
  max-height: 500px; /* A value larger than expected content height */
  opacity: 1;
  visibility: visible;
  padding: 15px 20px;
}

Notice the clever use of `max-height: 0` and `overflow: hidden` on the `.accordion-panel`. When `max-height` transitions from `0` to a large value (like `500px`), it creates a smooth "slide down" effect without having to know the exact content height. This technique is far more performant than manipulating `height` directly with JavaScript, which can trigger costly reflows. We're also using `opacity` and `visibility` for a more nuanced fade-in effect. GitHub's settings pages and many modern dashboards employ similar CSS-driven transitions for their collapsible sections, prioritizing smooth user feedback without heavy JS.

Crafting Seamless Transitions

The `transition` property on `.accordion-panel` is key. It specifies that changes to `max-height`, `opacity`, and `visibility` should animate over 0.3 seconds with an `ease-out` timing function. This makes the opening and closing feel fluid and responsive, a crucial detail for a polished user experience. We're not using JavaScript to animate; we're simply adding or removing a class, and CSS handles the rest. This separation of concerns—HTML for structure, CSS for presentation, JavaScript for behavior—is a cornerstone of robust web development.

Leveraging CSS Custom Properties

You'll see `var(--accordion-border-color, #ccc)` and similar declarations in the CSS. These are CSS Custom Properties (variables). They allow you to define reusable values, making it incredibly easy to theme your accordion without touching a single line of JavaScript. Want to change the header background color across your entire site? Just update `--accordion-header-bg` in your root CSS, and every accordion will instantly reflect the change. This promotes consistency, as highlighted in articles like Why You Should Use a Consistent Spacing System for Your Site, and drastically simplifies maintenance.

The JavaScript Engine: Toggling State and Enhancing Interaction

Now for the crucial part: the JavaScript that ties it all together. Our goal is to make the accordion functional, managing the `aria-expanded` state and toggling the `is-expanded` class on the content panel. We'll use vanilla JavaScript, avoiding any libraries, to keep our solution as lightweight and performant as possible.

document.addEventListener('DOMContentLoaded', () => {
  const accordionTriggers = document.querySelectorAll('.accordion-trigger');

  accordionTriggers.forEach(trigger => {
    trigger.addEventListener('click', () => {
      const isExpanded = trigger.getAttribute('aria-expanded') === 'true';
      const targetPanelId = trigger.getAttribute('aria-controls');
      const targetPanel = document.getElementById(targetPanelId);

      // Close all other open accordions in the same group (optional, but common behavior)
      // If you want multiple accordions to be open simultaneously, remove this loop.
      document.querySelectorAll('.accordion-trigger[aria-expanded="true"]').forEach(openTrigger => {
        if (openTrigger !== trigger) {
          openTrigger.setAttribute('aria-expanded', 'false');
          const openPanel = document.getElementById(openTrigger.getAttribute('aria-controls'));
          if (openPanel) {
            openPanel.classList.remove('is-expanded');
            openPanel.setAttribute('hidden', ''); // Hide from screen readers
          }
        }
      });

      // Toggle the clicked accordion
      if (isExpanded) {
        trigger.setAttribute('aria-expanded', 'false');
        if (targetPanel) {
          targetPanel.classList.remove('is-expanded');
          targetPanel.setAttribute('hidden', ''); // Hide from screen readers
        }
      } else {
        trigger.setAttribute('aria-expanded', 'true');
        if (targetPanel) {
          targetPanel.classList.add('is-expanded');
          targetPanel.removeAttribute('hidden'); // Show to screen readers
        }
      }
    });
  });
});

This script first waits for the DOM to be fully loaded. Then, it selects all elements with the class `accordion-trigger`. For each trigger, it adds a `click` event listener. Inside the listener, it checks the current `aria-expanded` state. If the accordion is already expanded, it collapses it; otherwise, it expands it. Crucially, it updates both the `aria-expanded` attribute on the button and toggles the `is-expanded` class on the content panel, which our CSS uses to animate the transition. It also toggles the `hidden` attribute to ensure screen readers correctly interpret the panel's visibility. This direct manipulation of attributes and classes is the essence of vanilla JS efficiency. Sites like BBC News have long employed similar minimalist JavaScript patterns for their mobile navigation toggles, prioritizing speed and broad device compatibility.

Advanced Accessibility Considerations: Keyboard Navigation and Screen Readers

An accordion isn't truly functional if it's only navigable by mouse. Robust keyboard navigation is a cornerstone of web accessibility, ensuring that users who can't use a mouse (due to motor impairments, preference, or device limitations) can still interact fully with your content. Our current JavaScript handles basic activation via the `Enter` or `Space` key because the trigger is a `` element. Buttons inherently respond to these keys. But wait, there's more. We need to ensure logical tab order and potentially enhance navigation with arrow keys. The `tabindex="0"` attribute is implicitly handled for our `` elements, meaning they're naturally part of the document's tab sequence. When a user tabs through the page, they'll land on each accordion trigger. Pressing `Enter` or `Space` will toggle its state. This covers the most basic requirement. However, for a truly excellent experience, especially with multiple accordion items, keyboard users often expect to navigate between triggers using the up and down arrow keys, similar to how they'd navigate tabs or menus.

Ensuring WCAG Compliance

The Web Content Accessibility Guidelines (WCAG) 2.1 (2018) at Level AA require that all functionality be operable via a keyboard. Our current implementation meets this for basic toggling. For enhanced arrow-key navigation, you'd extend the JavaScript to listen for `keydown` events, specifically checking for `ArrowUp` and `ArrowDown` keys. If detected, you'd programmatically shift focus to the previous or next `accordion-trigger` element, ensuring the focus wraps around from the last to the first, and vice-versa. This level of detail, while often overlooked in quick implementations, significantly improves the experience for power users and those relying on assistive tech. For example, the US Web Design System (USWDS), used by many U.S. government websites, features an accordion component with this exact arrow-key navigation, setting a high standard for keyboard operability.

Performance Optimization: Beyond the Initial Load

While our vanilla CSS and JS approach inherently offers superior performance compared to framework-heavy alternatives, there are still ways to fine-tune it. Performance optimization isn't just about initial page load; it’s about maintaining responsiveness and efficiency throughout the user's interaction. One common scenario is when accordion panels contain complex content, such as images, videos, or even other interactive components. If these elements are loaded regardless of whether the panel is open, you're wasting resources. Consider lazy loading:

You'd modify the JavaScript to check the `data-lazy-loaded` attribute when a panel is expanded. If `false`, fetch the content (e.g., from an AJAX call or by populating `data-src` attributes into `src` for images) and then set `data-lazy-loaded="true"`. This ensures resources are only consumed when actually needed. Google Developers' performance best practices often highlight conditional loading of resources as a key strategy, minimizing initial payload. Another area is minimizing layout shifts. While our `max-height` transition is efficient, if the accordion's content dramatically changes its height after loading (e.g., dynamically inserted content with unknown dimensions), it can cause visual jumps. Pre-allocating space or using `min-height` with `max-height` can help mitigate this, though it adds complexity. For most simple accordions, the `max-height` transition is sufficient and highly performant.

Real-World Applications and Scalability

The beauty of this vanilla approach to implementing a simple accordion with CSS and JS isn't just its efficiency; it's its inherent scalability and adaptability. This isn't a fragile, one-off solution; it's a foundational pattern that can be extended and customized for a myriad of real-world use cases without incurring technical debt. Consider an e-commerce product page. You might have accordions for "Product Details," "Specifications," "Reviews," and "Shipping Information." Each of these sections might vary wildly in content length. Our `max-height` CSS transition gracefully handles these variations. What about a complex FAQ page with dozens of questions? A vanilla implementation means you're not importing a heavy library for every single page just to render simple collapsible questions. The Salesforce Lightning Design System, for example, emphasizes building highly performant, accessible UI components with minimal JavaScript, often using patterns very similar to what we've outlined. They understand that every byte and every millisecond counts, especially in enterprise applications. This pattern is also incredibly robust for progressive enhancement. Even if JavaScript fails or is disabled (a rare but possible scenario), the underlying HTML `h3` and `div` structure would still be present, albeit without the expand/collapse functionality. If you used the native `

` and `

` elements, the accordion would function fully even without any JavaScript or CSS – a testament to the power of native HTML. This approach fosters a resilient web, ensuring core content remains accessible under diverse conditions. It’s a pragmatic choice for long-term project health and user satisfaction.

Step-by-Step Guide: Building Your Accordion from Scratch

Building your own vanilla CSS and JavaScript accordion involves a series of clear, actionable steps. Follow these instructions to create a performant and accessible component:

• Define Your HTML Structure: Start with a `div.accordion` container. Inside, create multiple `div.accordion-item` elements. Each item needs an `h3` containing a `

` (`.accordion-trigger`) and a `div` (`.accordion-panel`) for the content.

Implement ARIA Attributes: On each button, add `id`, `aria-expanded="false"`, and `aria-controls` (pointing to the panel's ID). On each panel, add `id`, `role="region"`, `aria-labelledby` (pointing to the button's ID), and the `hidden` attribute.

Apply Base CSS Styling: Style your `.accordion-item`, `.accordion-trigger`, and `.accordion-panel` for visual clarity. Ensure `.accordion-trigger` is a full-width button with appropriate padding and cursor.

Set Up CSS Transitions: Crucially, apply `max-height: 0; opacity: 0; visibility: hidden;` to `.accordion-panel` in its default state, along with a `transition` property for these values.

Create an "Expanded" CSS Class: Define a `.accordion-panel.is-expanded` class that sets `max-height` to a sufficiently large value (e.g., `500px`), `opacity: 1`, `visibility: visible`, and adds desired internal padding.

Write Vanilla JavaScript: Use `document.querySelectorAll('.accordion-trigger')` to select all your buttons. Iterate over them, adding an `addEventListener('click', ...)` to each.

Toggle State in JavaScript: Inside the event listener, get the `aria-expanded` state and the target panel's ID. Toggle `aria-expanded` on the button and add/remove the `is-expanded` class and `hidden` attribute on the corresponding panel.

Test Thoroughly: Verify functionality with both mouse and keyboard navigation (Tab, Enter, Space). Use browser developer tools to inspect ARIA attributes and CSS class changes. Test with a screen reader if possible.

"A 2023 study by Portent found that a 1-second delay in mobile page load time can lead to a 20% drop in conversion rates for e-commerce sites. Speed isn't just a feature; it's a fundamental business driver." (Portent, 2023)

What the Data Actually Shows

The evidence is clear: for foundational UI components like an accordion, the perceived "convenience" of heavy JavaScript frameworks often comes at a significant cost to performance, accessibility, and long-term maintainability. Our deep dive into building a simple accordion with pure CSS and JavaScript isn't just a theoretical exercise; it’s a strategic decision backed by industry data and accessibility standards. By taking control of the code, developers can deliver a faster, more inclusive, and ultimately more robust user experience, eliminating unnecessary bloat and technical debt. This approach proves that true simplicity lies in elegance and efficiency, not in opaque, heavy dependencies.

What This Means for You

Understanding how to implement a simple accordion with CSS and JS has direct, practical implications for your web projects and career:

1. Boost Your Site's Performance: By shedding unnecessary JavaScript, your pages will load faster, improving Core Web Vitals scores and user retention. This directly impacts SEO and conversion rates, as demonstrated by the Portent (2023) study.
2. Enhance Accessibility for All Users: Building from the ground up ensures you implement critical ARIA attributes and keyboard navigation, adhering to WCAG 2.1 standards. This isn't just good practice; it's a legal and ethical imperative.
3. Reduce Technical Debt and Improve Maintainability: A lean, vanilla solution is easier to understand, debug, and update than one reliant on complex framework internals. Your team will spend less time wrestling with external dependencies and more time innovating.
4. Gain Deeper Control and Flexibility: Without the constraints of a framework, you have complete control over styling, behavior, and responsiveness. This allows for highly customized designs and ensures your accordion perfectly fits your project's unique needs.

Frequently Asked Questions

What are the primary benefits of building an accordion without a JavaScript library?

Building an accordion without a JavaScript library drastically reduces your page's JavaScript bundle size, leading to faster load times and improved performance. It also gives you granular control over accessibility features, ensuring compliance with WCAG standards without fighting framework defaults.

How does a vanilla CSS and JS accordion impact page load speed?

A vanilla CSS and JS accordion significantly improves page load speed by eliminating the need to download, parse, and execute large, often unused, JavaScript files from frameworks. This can reduce initial load times by hundreds of milliseconds, positively impacting user experience and SEO.

Is it more difficult to maintain a custom accordion compared to a framework component?

While initial setup requires more lines of code than a framework's single component tag, a custom vanilla accordion is often easier to maintain long-term. You control every line, there are no breaking changes from library updates, and debugging is simpler since you're not dealing with abstract framework logic.

What is the most crucial accessibility feature for an accordion?

The most crucial accessibility feature for an accordion is proper ARIA (Accessible Rich Internet Applications) attribute usage, specifically `aria-expanded` on the button and `aria-controls` on the button pointing to the panel ID. This, combined with robust keyboard navigation (Tab, Enter, Space keys), ensures screen readers and keyboard users can effectively interact with the component.