Accordion

Accordion creates expandable content sections with smooth open and close animations. The visual structure is driven by CSS — the Hygular runtime handles interaction, state, animation, and lifecycle events automatically through delegated event handling.

Accordion is suited for FAQ sections, settings panels, documentation navigation, product detail pages, sidebar menus, and any interface that benefits from progressive disclosure.


Getting Started

Add data-hygular="accordion" to the root element so the Hygular runtime can activate delegated behavior. No manual event listeners are needed.

  <div class="accordion" data-hygular="accordion">
    <div class="accordion-item">
      <button class="button accordion-toggler">What is Hygular</button>
      <div class="accordion-content">
        <div class="accordion-inner">
          Hygular combines a design-token CSS foundation with an intelligent JavaScript runtime.
        </div>
      </div>
    </div>

    <div class="accordion-item">
      <button class="button accordion-toggler">Can I use it with React?</button>
      <div class="accordion-content">
        <div class="accordion-inner">
          Yes. Hygular provides a React integration layer for hooks and lifecycle cleanup.
        </div>
      </div>
    </div>
  </div>

Runtime

The Javascript runtime is required for the Accordion component to function correctly. To do this, a new Hygular instance must be created on the page. React users, however, simply need to use the useAccordion hook.

'use client';

import { useAccordion } from '@hygular/core/react';

export function AccordionExample() {
  useAccordion();

  return (
    <div className="accordion" data-hygular="accordion">
      <div className="accordion-item">
        <button className="accordion-toggler">What is Hygular?</button>
        <div className="accordion-content">
          <p>Hygular is a UI component library with React integration out of the box.</p>
        </div>
      </div>
      <div className="accordion-item">
        <button className="accordion-toggler">How do I install it?</button>
        <div className="accordion-content">
          <p>Run <code>npm install @hygular/core</code> and import the CSS and hooks.</p>
        </div>
      </div>
    </div>
  );
}

After new Hygular() runs on the client, delegated accordion behavior is activated. You do not need to manually attach event listeners to each item.

Hygular combines a design-token CSS foundation with an intelligent JavaScript runtime.

Yes. Hygular provides a React integration layer for hooks and lifecycle cleanup.

Structure

The accordion markup is intentionally simple.

ElementClass / attributePurpose
RootaccordionGroups accordion items.
Runtime markerdata-hygular="accordion"Marks the component for Hygular runtime behavior.
Itemaccordion-itemWraps one toggle and one content panel.
Triggeraccordion-togglerClickable element that opens or closes the panel.
Panelaccordion-contentCollapsible content region.
Inner wrapperaccordion-innerProvides consistent content padding.

Basic Example

<div class="accordion" data-hygular="accordion">
  <div class="accordion-item">
    <button class="accordion-toggler">
      Installation
    </button>

    <div class="accordion-content">
      <div class="accordion-inner">
        Install Hygular from modern ESM or use the CDN build.
      </div>
    </div>
  </div>

  <div class="accordion-item">
    <button class="accordion-toggler">
      Runtime
    </button>

    <div class="accordion-content">
      <div class="accordion-inner">
        The runtime initializes delegated component behavior on the client.
      </div>
    </div>
  </div>
</div>

Configuration Attributes

Accordion supports runtime attributes on the root element.

AttributeDefaultBehavior
data-allow-multiplefalseSet to true to allow multiple open panels.
data-open-firstfalseWhen set to true, the first accordion item is opened on initialization.

Single Open Mode

By default, Accordion keeps only one item open at a time.

When a new panel opens, the runtime closes other opened panels in the same accordion root.

<div class="accordion" data-hygular="accordion">
  <div class="accordion-item">
    <button class="accordion-toggler">First</button>
    <div class="accordion-content">
      <div class="accordion-inner">First panel</div>
    </div>
  </div>

  <div class="accordion-item">
    <button class="accordion-toggler">Second</button>
    <div class="accordion-content">
      <div class="accordion-inner">Second panel</div>
    </div>
  </div>
</div>

Multiple panels are allowed only when data-allow-multiple="true". Otherwise, opening a panel closes the other open panels in the same root.

Multiple Open Panels

Set data-allow-multiple="true" when multiple panels should be allowed to stay open.

<div class="accordion" data-hygular="accordion" data-allow-multiple="true">
  <div class="accordion-item">
    <button class="button accordion-toggler">Account</button>
    <div class="accordion-content">
      <div class="accordion-inner">Account settings.</div>
    </div>
  </div>

  <div class="accordion-item">
    <button class="button accordion-toggler">Notifications</button>
    <div class="accordion-content">
      <div class="accordion-inner">Notification settings.</div>
    </div>
  </div>
</div>
Account settings.
Notification settings.

Open First Item on Load

Set data-open-first="true" when the first accordion item should be open after initialization.

<div class="accordion" data-hygular="accordion" data-open-first="true">
  <div class="accordion-item">
    <button class="button accordion-toggler">Account</button>
    <div class="accordion-content">
      <div class="accordion-inner">Account settings.</div>
    </div>
  </div>

  <div class="accordion-item">
    <button class="button accordion-toggler">Notifications</button>
    <div class="accordion-content">
      <div class="accordion-inner">Notification settings.</div>
    </div>
  </div>
</div>

The runtime adds the is-open class to the first toggler and sets the first content panel to display: block.

Account settings.
Notification settings.

Size Variants

Accordion supports size variants on the root element.

ClassEffectBest for
accordionDefault compact spacing.General content and sidebars.
is-mediumIncreases item and inner spacing.Documentation pages and settings panels.
is-largeProvides the most spacious layout.Marketing sections and FAQ blocks.
<div class="accordion is-medium" data-hygular="accordion" data-open-first="false">
  <div class="accordion-item">
    <button class="button accordion-toggler">Account</button>
    <div class="accordion-content">
      <div class="accordion-inner">Account settings.</div>
    </div>
  </div>

  <div class="accordion-item">
    <button class="button accordion-toggler">Notifications</button>
    <div class="accordion-content">
      <div class="accordion-inner">Notification settings.</div>
    </div>
  </div>
</div>

Account settings.
Notification settings.

Open State

The runtime uses the is-open class on the toggler to rotate the indicator icon.

StateClassBehavior
ClosedNo is-open classThe content panel remains hidden.
Openis-openThe indicator rotates and the content panel becomes visible.
.accordion-toggler.is-open::after {
  transform: rotate(180deg);
}

The content panel starts with display: none. The runtime opens and closes it with slide animations.

Icon Indicator

Accordion togglers include a built-in arrow indicator through CSS.

The icon is created with a masked SVG and uses currentColor, so it automatically follows the text color of the toggler.

.accordion-toggler::after {
  margin-inline-start: auto;
  background-color: currentColor;
  transition: transform 0.15s ease-out, opacity 0.15s ease-out;
}

This keeps the indicator theme-aware without requiring extra markup.

FAQ Pattern

<section>
  <h2>Frequently Asked Questions</h2>

  <div class="accordion is-medium" data-hygular="accordion" data-open-first="true">
    <div class="accordion-item">
      <button class="button accordion-toggler">
        Does Hygular require a build step?
      </button>

      <div class="accordion-content">
        <div class="accordion-inner">
          No. You can use Hygular through CDN or ESM depending on your workflow.
        </div>
      </div>
    </div>

    <div class="accordion-item">
      <button class="button accordion-toggler">
        Can I use it with React?
      </button>

      <div class="accordion-content">
        <div class="accordion-inner">
          Yes. Use the React integration layer for hooks and runtime helpers.
        </div>
      </div>
    </div>
  </div>
</section>

Frequently Asked Questions

No. You can use Hygular through CDN or ESM depending on your workflow.

Yes. Use the React integration layer for hooks and runtime helpers.

Runtime Behavior

Accordion is initialized through the Hygular runtime.

When new Hygular() runs, the delegated component system listens for clicks on .accordion-toggler, finds the closest [data-hygular="accordion"] root, and updates the related .accordion-content.

BehaviorDescription
Delegated eventsAccordion triggers do not need individual listeners.
LockingThe root uses an internal lock while animations are running.
Single-open modeBy default, opening one panel closes other open panels in the same root.
Multiple-open modedata-allow-multiple="true" allows multiple panels to remain open.
Default open modedata-open-first="true" opens the first item when initialized.
Slide animationThe runtime uses slide up and slide down helpers for open and close transitions.

Lifecycle Events

Accordion dispatches lifecycle events before and after opening or closing.

The open and close events are cancelable. Call event.preventDefault() to stop the action.

EventCancelableWhen it fires
hygular.accordion.openYesBefore a panel opens.
hygular.accordion.openedNoAfter a panel opens.
hygular.accordion.closeYesBefore a panel closes.
hygular.accordion.closedNoAfter a panel closes.

Each event includes trigger, content, and item in event.detail.

document.addEventListener('hygular.accordion.opened', (event) => {
  const { trigger, content, item } = event.detail;

  console.log('Accordion opened:', trigger, content, item);
});

Prevent Opening

Use the cancelable hygular.accordion.open event when an accordion panel should not open under certain conditions.

document.addEventListener('hygular.accordion.open', (event) => {
  const { trigger } = event.detail;

  if (trigger.dataset.locked === 'true') {
    event.preventDefault();
  }
});

React Usage

For React and Next.js projects, use the React integration layer instead of manually wiring accordion behavior inside every component.

import { useAccordion } from '@hygular/core/react';

export function FAQAccordion() {
  useAccordion();

  return (
    <div className="accordion is-medium" data-hygular="accordion" data-open-first="true">
      <div className="accordion-item">
        <button className="button accordion-toggler">
          Does Hygular work with React?
        </button>

        <div className="accordion-content">
          <div className="accordion-inner">
            Yes. The React integration layer connects Hygular behavior to React apps.
          </div>
        </div>
      </div>
    </div>
  );
}

Continue with the React Integration guide for hooks, runtime helpers, and Next.js usage.

Accessibility

Use semantic buttons for accordion toggles.

Recommended practices:

  • Use <button> for .accordion-toggler.
  • Keep the button text descriptive.
  • Do not put important content only inside collapsed panels.
  • Keep the DOM order logical.
  • Avoid using accordion behavior for critical navigation unless the collapsed state remains understandable.

If your application requires strict WAI-ARIA accordion semantics, you may add aria-expanded, aria-controls, and matching panel IDs in your markup.

<button
  class="accordion-toggler"
  aria-expanded="false"
  aria-controls="faq-panel-1">
  What is Hygular?
</button>

<div id="faclass="accordion-content">
  <div class="accordion-inner">
    Hygular is a modern UI engine.
  </div>
</div>

Class Reference

ClassRole
accordionRoot accordion wrapper.
accordion-itemSingle accordion section.
accordion-togglerClickable trigger element.
accordion-contentCollapsible panel.
accordion-innerInner content wrapper with padding.
is-openActive state class applied to the toggler.
is-mediumMedium accordion spacing variant.
is-largeLarge accordion spacing variant.

Notes

  • Accordion requires the Hygular runtime for interaction.
  • Initialize the runtime once with new Hygular().
  • The root must include data-hygular="accordion".
  • The CSS controls structure, spacing, colors, and the indicator icon.
  • The runtime controls opening, closing, animation, events, and state classes.
  • data-allow-multiple="true" allows multiple panels to remain open.
  • data-open-first="true" opens the first item during initialization.
  • Use the React hook only in React or Next.js applications.
  • Use the React Integration guide when building with React.

Hygular