Expand Toggle

Simple and accessible expandable functionality, similar to jQuery’s slideToggle() method.

Inspired by:

• https://inclusive-components.design/menus-menu-buttons#truemenus
• https://www.stefanjudis.com/snippets/how-to-animate-height-with-css-grid/

Install

yarn add @threespot/expand-toggle

Requires Node 20+. The package ships as an ES module ("type": "module"); consumers using CommonJS will need to load it via dynamic import().

Usage

JavaScript

import ExpandToggle from "@threespot/expand-toggle";

document.querySelectorAll("[data-expands]").forEach(el => new ExpandToggle(el));

Markup

<button type="button" data-expands="demo" data-expands-class="is-expanded">
  <span data-expands-text="Close">Open</span>
</button>

<div class="expandable" id="demo">
  <div class="expandable-wrap">
    <p>This content will be hidden to start.</p>
  </div>
</div>

Styles

The package ships a Sass mixin that produces the required styles. The expandable element needs a single child wrapper for overflow: hidden; the mixin targets & > *.

@use "@threespot/expand-toggle/expandable.scss" as et;

// The class name is just an example
.expandable {
  @include et.expandable;
}

The .scss extension is required — the package's exports map declares ./expandable.scss explicitly, so Sass cannot fall back to the partial-style resolution it normally uses for extensionless paths.

Override the animation with two CSS custom properties (defaults: 400ms and ease-out):

:root {
  --expand-speed: 500ms;
  --expand-easing: cubic-bezier(0.4, 0, 0.2, 1);
}

The mixin honors prefers-reduced-motion and applies the expanded state under .no-js so navigation menus remain usable without JavaScript.

Options

data-expands-class defines a class (or multiple classes) to apply to the toggle button and expandable element when expanded

data-expands-text defines button text to use when expanded. The element carrying this attribute should contain only text; mixing in icons (e.g. an inline <svg>) is not recommended. If you do mix them, only the first text node is swapped on expand/collapse, leaving siblings untouched — but the cleaner pattern is to wrap the swappable copy in its own element (e.g. a nested <span data-expands-text="Close">Open</span> next to a sibling icon).

data-expanded will expand the element by default

data-expands-haspopup opts the toggle into aria-haspopup and sets its value (e.g. data-expands-haspopup="menu" or data-expands-haspopup="dialog"). Omit unless the expandable behaves like a menu, dialog, listbox, tree, or grid — the WAI-ARIA Disclosure pattern does not use aria-haspopup.

The following options can be set via JavaScript:

new ExpandToggle(el, {
  expandedClasses: "", // string, accepts multiple space-separated classes
  activeToggleText: "", // expanded state toggle button text
  shouldStartExpanded: false, // component starts expanded on init
  ariaHasPopup: false, // false, true, or an ARIA 1.1 value ("menu", "dialog", "listbox", "tree", "grid")
  onReady: null // ready callback function
});

Events

ready

Since the ready event may be trigger immediately, bind using the onReady option:

const toggle = new ExpandToggle(el, {
  onReady: function() {
    console.log('ready');
  }
});

expand

Triggered when component is expanded

toggle.on('expand', function() {
  console.log('expand');
});

collapse

Triggered when component is collapsed

toggle.on('collapse', function() {
  console.log('collapse');
});

destroy

Triggered when component is destroyed

toggle.on('destroy', function() {
  console.log('destroy');
});

Development

yarn install
yarn test            # run the suite (node --test against happy-dom)
yarn test:coverage   # same, with experimental test coverage

There is no build step. index.js is the published source.

License

This is free software and may be redistributed under the terms of the MIT license.

About Threespot

Threespot is an independent digital agency hell-bent on helping those, and only those, who are committed to helping others. Find out more at https://www.threespot.com.