Collapse

When to use

Use collapse when there's content most people won't need right away, such as an FAQ answer, extra details on a product, or a "show more" block, and you want to keep the page short without hiding that content away on another screen. It's not the right tool for content that should always stay visible and merely feel less prominent (dim it with CSS instead). A closed collapse panel is completely removed from the page for anyone using a screen reader, not just visually tucked away. See Alternatives below for when the content should overlay the page instead, or stay in an even more compact footprint.

Install & usage

Pick a framework in the toolbar above and these snippets adapt.

npm install @eunomia/elements

import "@eunomia/elements/collapse.js";

<eun-collapse heading="What is your return policy?">
  You can return any item within 30 days of delivery for a full refund.
</eun-collapse>

document
  .querySelector("eun-collapse")
  .addEventListener("eunchange", (event) => {
    console.log(event.target.open);
  });

npm install @eunomia/elements

<script type="module">
  import "@eunomia/elements/collapse.js";
</script>

<eun-collapse heading="What is your return policy?">
  You can return any item within 30 days of delivery for a full refund.
</eun-collapse>

<script>
  document
    .querySelector("eun-collapse")
    .addEventListener("eunchange", (event) => {
      console.log(event.target.open);
    });
</script>

npm install @eunomia/elements

import "@eunomia/elements/collapse.js";

function ReturnPolicy() {
  return (
    <eun-collapse
      heading="What is your return policy?"
      oneunchange={(event) => console.log(event.target.open)}
    >
      You can return any item within 30 days of delivery for a full refund.
    </eun-collapse>
  );
}

npm install @eunomia/elements

"use client";
import "@eunomia/elements/collapse.js";

export function ReturnPolicy() {
  return (
    <eun-collapse
      heading="What is your return policy?"
      oneunchange={(event) => console.log(event.target.open)}
    >
      You can return any item within 30 days of delivery for a full refund.
    </eun-collapse>
  );
}

npm install @eunomia/elements

<script setup>
  import "@eunomia/elements/collapse.js";
</script>

<template>
  <eun-collapse
    heading="What is your return policy?"
    @eunchange="(event) => console.log(event.target.open)"
  >
    You can return any item within 30 days of delivery for a full refund.
  </eun-collapse>
</template>

npm install @eunomia/elements

import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
import "@eunomia/elements/collapse.js";

@Component({
  selector: "app-return-policy",
  template: `
    <eun-collapse
      heading="What is your return policy?"
      (eunchange)="onChange($event)"
    >
      You can return any item within 30 days of delivery for a full refund.
    </eun-collapse>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class ReturnPolicyComponent {
  onChange(event: Event) {
    console.log((event.target as HTMLElement & { open: boolean }).open);
  }
}

Alternatives

Guidance

Live testing

Properties

Basic

<eun-collapse heading="What is your return policy?">
  You can return any item within 30 days of delivery for a full refund.
</eun-collapse>

Header

Subheading

<eun-collapse heading="Shipping" subheading="Delivery times and carriers">
  ...
</eun-collapse>

Leading icon

<eun-collapse heading="Shipping" icon="local_shipping">...</eun-collapse>

Need something other than a eun-icon, or full control over it? Slot your own non-interactive content into icon instead. It replaces the prop-driven icon entirely.

<eun-collapse heading="Shipping">
  <span
    slot="icon"
    aria-hidden="true"
    style="
      display: flex;
      align-items: center;
      justify-content: center;
      width: 20px;
      height: 20px;
      border-radius: 999px;
      background: #148cd2;
      color: #fff;
      font-size: 12px;
      font-weight: bold;
    "
    >!</span
  >
  ...
</eun-collapse>

Tag

A short label rendered as a default eun-tag in the trigger, e.g. a count or category.

<eun-collapse heading="Do you ship internationally?" tag="Popular">
  ...
</eun-collapse>

The tag prop only covers the default look. For a specific type/color/severity, slot your own eun-tag into tag instead. A custom element slotted there replaces the prop-driven tag entirely, while a plain element, such as a span of text, keeps the default tag style.

<eun-collapse heading="Do you ship internationally?">
  <eun-tag slot="tag" type="outline" severity="warning" rounded
    >Limited</eun-tag
  >
  ...
</eun-collapse>

Trailing indicator

Defaults to a plus sign (add) that rotates 45deg into a cross while open. A different icon usually needs a different rotation, e.g. a chevron wants to flip 180deg, not 45deg, so chevron-icon and --collapse-chevron-rotation are set together.

<eun-collapse
  heading="..."
  chevron-icon="keyboard_arrow_down"
  style="--collapse-chevron-rotation: 180deg;"
  >...</eun-collapse
>

For anything rotation can't express, such as swapping the icon itself rather than turning it, slot your own non-interactive content into chevron and set the rotation to 0deg to opt out of the built-in animation entirely.

<eun-collapse heading="..." style="--collapse-chevron-rotation: 0deg;">
  <eun-icon slot="chevron" name="keyboard_arrow_down" size="20"></eun-icon>
  ...
</eun-collapse>

collapse.addEventListener("eunchange", () => {
  icon.name = collapse.open ? "keyboard_arrow_up" : "keyboard_arrow_down";
});

Content

Custom content

The default slot accepts anything, not just text. Only the panel's own padding applies to whatever is slotted in. No margins, typography, or list styles are ever forced onto it beyond ordinary CSS inheritance (color/font-family/font-size, which any slotted element can still override locally). Build the panel body entirely yourself for content you're authoring by hand, or when rich-text's small Markdown-like subset isn't enough. See "Rich text" below for the opposite case, a plain string arriving at runtime rather than markup you write yourself.

<eun-collapse heading="Invite a teammate">
  <form>
    <input type="email" placeholder="teammate@company.com" />
    <button type="submit">Send invite</button>
  </form>
</eun-collapse>

Rich text

rich-text accepts a small Markdown-like subset (- item lists, [label](url) links, **bold**, *italic*) rendered above the default slot, so both can combine. No HTML string is ever built (no unsafeHTML), so arbitrary content can never inject markup. It's the same engine (and the same non-standard "Markdown-lite" syntax) as eun-textarea's own formatting toolbar. See Markdown-lite for the full syntax reference. Set it from JavaScript rather than as a plain HTML attribute once it spans more than one line. A blank line inside an HTML tag's attribute value trips up this page's own Markdown-to-HTML build step, not eun-collapse itself, the same reason every multi-paragraph example on the Markdown guide page above is wired up the same way.

Reach for it specifically when the content is a plain string arriving at runtime that you have no HTML to author for, such as a CMS-driven FAQ answer or a description fetched from an API. When you're writing the content by hand in your own template instead, slot real markup into the default slot directly (see "Custom content" above). It skips the Markdown-lite subset and its limitations entirely, at the cost of writing actual HTML instead of a plain string.

<eun-collapse
  id="return-policy"
  heading="What is your return policy?"
  tag="Popular"
></eun-collapse>

document.querySelector("#return-policy").richText =
  "Returns are accepted within **30 days** of delivery.\n\n" +
  "Before sending anything back :\n" +
  "- Contact [our support team](https://example.com/support) to get a return label\n" +
  "- Pack the item securely in its original box";

States

Open by default

<eun-collapse heading="What is your return policy?" open>...</eun-collapse>

Disabled

<eun-collapse heading="What is your return policy?" disabled>...</eun-collapse>

Groups

Several

Each eun-collapse gets its own level="3" here, matching the fact that these three FAQ questions sit at the same depth in the page's own outline. See the Accessibility tab for why that's opt-in rather than automatic. Each instance opens and closes fully on its own. Opening one never closes the others, since eun-collapse has no concept of a shared group (see "Exclusive (accordion)" below for linking their open state together yourself).

<eun-collapse heading="What is your return policy?" level="3">...</eun-collapse>
<eun-collapse heading="How long does shipping take?" level="3"
  >...</eun-collapse
>
<eun-collapse heading="Do you ship internationally?" level="3"
  >...</eun-collapse
>

Independent

By default the trigger and panel merge into one flush shape (square corners at the shared edge, a divider line) which reads as "connected" and suits a single collapse, or a group meant to look like one continuous list (e.g. the accordion below). Set independent instead when a collapse sits side by side with others with no shared exclusivity between them, so the layout doesn't visually suggest a connection that isn't there. It renders the trigger and panel as two fully rounded, separated boxes with a gap, and drops the divider.

<eun-collapse heading="What is your return policy?" independent
  >...</eun-collapse
>

Exclusive (accordion)

To get the classic "only one open at a time" accordion behavior, listen for eunchange on each item and close the others whenever one opens. There's no prop for this, since not every group of collapses wants it. Left without independent here on purpose: this group behaves as one connected accordion, so the default flush shape (no gap, no rounded corners at the shared edge) reads correctly. See "Independent" above for when the opposite (separated, rounded) shape is the right call instead.

<div id="faq">
  <eun-collapse heading="What is your return policy?" level="3"
    >...</eun-collapse
  >
  <eun-collapse heading="How long does shipping take?" level="3"
    >...</eun-collapse
  >
  <eun-collapse heading="Do you ship internationally?" level="3"
    >...</eun-collapse
  >
</div>

const items = document.querySelectorAll("#faq eun-collapse");
items.forEach((item) => {
  item.addEventListener("eunchange", () => {
    if (!item.open) return;
    items.forEach((other) => {
      if (other !== item) other.open = false;
    });
  });
});

Each item only closes the others when it is the one firing eunchange as open, reacting to open becoming true rather than reading event.target inside a shared handler, so a eunchange fired by one item closing (from this very logic) never cascades into re-closing the others again.

Server-side rendering

Link collapse-ssr.css in the page's <head> to draw the final collapse from the first paint:

<link
  rel="stylesheet"
  href="node_modules/@eunomia/elements/dist/ssr/collapse-ssr.css"
/>

A bundler that resolves package exports (Vite, webpack, Turbopack, or a Sass @use/@import) can reach the same file through the package specifier instead, which survives a hoisted or monorepo install the raw path above doesn't:

@use "@eunomia/elements/collapse-ssr.css";

It draws the trigger with the heading, subheading, icon and tag slots, hides the panel of a closed collapse, and shows the panel of one whose open attribute is written in the server-rendered markup, under its divider. It covers disabled and the --collapse-* spacing and color properties, and keeps room for the chevron, which appears with the upgrade. The text of the heading attribute and an icon set through icon appear with the upgrade too, so prefer the slots. An open independent collapse is drawn as a single box until then. overlay-ssr.css also hides a closed panel, if it's already linked for other components.

Content indexed by search engines

The heading and rich-text attributes only render in the shadow root, so the server HTML carries them as attribute values, not as page content. Crawlers that don't run JavaScript never see that text. When the content matters for search (an FAQ, for example), pass the question through the heading slot and the answer through the default slot instead, so both are part of the server-rendered HTML:

<eun-collapse level="3">
  <span slot="heading">How long does a project take?</span>
  <p>Usually four to eight weeks, depending on its scope.</p>
</eun-collapse>

The slotted heading still renders inside the level heading element and the trigger button, exactly like the attribute does.

subheading and tag have slots of their own for the same reason. Text slotted into subheading keeps the subheading style, and a plain element slotted into tag keeps the default tag style:

<eun-collapse level="3">
  <span slot="heading">Design system lead</span>
  <span slot="subheading">2022 to 2024</span>
  <span slot="tag">Freelance</span>
  <p>Built and rolled out a component library across four products.</p>
</eun-collapse>

Customization

Spacing and typography

--collapse-heading-font-size and --collapse-subheading-font-size set the size of the heading and the subheading, and --collapse-heading-font-weight the weight of the heading. The panel uses the trigger's padding until --collapse-panel-padding gives it its own, for instance to drop the space above the answer. --collapse-divider-width and --collapse-divider-color style the line between the trigger and the panel, and a width of 0 removes it.

<eun-collapse
  heading="Do you deliver on Saturdays?"
  style="
    --collapse-heading-font-size: var(--eun-font-size-m);
    --collapse-panel-padding: 0 var(--eun-space-m) var(--eun-space-m);
    --collapse-divider-width: 0;
  "
  >...</eun-collapse
>

Custom colors

Every color is a CSS variable, with independent hooks for the closed, hovered, focused, and open states.

<eun-collapse
  heading="What is your return policy?"
  style="
    --collapse-background: #f4effa;
    --collapse-background-hover: #e9def5;
    --collapse-background-open: #071621;
    --collapse-color: #4a2e83;
    --collapse-color-hover: #6b3fc0;
    --collapse-color-open: #fff;
    --collapse-content-color: #d7d9e0;
  "
  >...</eun-collapse
>

--collapse-content-color is what keeps the panel's body text readable here. Without it, the body would inherit the default (dark) text color regardless of --collapse-background-open going dark, same as any other text sitting on a background it wasn't styled for.

Full list of custom properties in the API tab.

Parts

The trigger and panel parts reach what the variables don't cover, such as a line along the panel of a mobile menu's submenu.

eun-collapse::part(panel) {
  position: relative;
}
eun-collapse::part(panel)::before {
  content: "";
  position: absolute;
  inset-block: 0 var(--eun-space-m);
  left: var(--eun-space-m);
  width: 3px;
  border-radius: 3px;
  background: var(--eun-color-grey-300);
}

The custom properties that change colors, borders, shadows and corners, at a glance. The API tab lists every property of the component.

Keyboard and focus

Keyboard interactions

While collapsed, the panel is inert, so Tab normally skips over its content entirely, exactly as if it weren't in the page. The one exception is a panel holding at least one focusable element (a link, a button, a form field): tabbing forward off the trigger then opens the panel and lands focus on that first focusable element instead of jumping past it, so keyboard users are never stranded outside content they'd otherwise have no way to reach at all. Leaving the panel and trigger entirely afterward, whether by tabbing past the last focusable element or by tabbing back off the trigger itself, closes the panel again, but only if it was opened this way. A panel opened by clicking the trigger stays open no matter where focus goes next, exactly like any other disclosure. Opening it any other way, through a click or programmatically, makes it interactive immediately too, with no extra step needed.

Focus management

Closing the panel while focus is on something inside it (e.g. a link in the rich-text or slotted content) moves focus back to the trigger automatically, so keyboard focus is never dropped into now-inert, unreachable content, satisfying WCAG 2.4.3 Focus Order. If focus is already somewhere else on the page when the panel closes (e.g. closed programmatically, or from a different control entirely), focus is left untouched rather than being redirected.

Browser find-in-page

On engines that support it, the browser's own find-in-page (Ctrl+F / Cmd+F) can match text inside a closed panel and opens it automatically to show the match, using the same hidden="until-found" mechanism browsers use for native disclosure widgets. Fragment navigation to an anchor inside a closed panel reveals it the same way. Engines without that support keep closed panels fully out of find-in-page's reach instead, falling back to the same inert exclusion already used while disabled, so no content ever becomes silently unsearchable-looking without actually being searchable.

Semantics and screen readers

Trigger semantics

The trigger renders as a real, native <button type="button"> with aria-expanded reflecting open and aria-controls pointing at the panel, matching the WAI-ARIA APG Disclosure pattern exactly, and satisfying WCAG 4.1.2 Name, Role, Value without any manual ARIA wiring on your part. aria-controls="panel" references an id scoped to the component's own shadow root, so it stays correct and non-colliding even with several eun-collapse instances on the same page.

Because the panel is genuinely inert, or hidden="until-found" on engines that support find-in-page reveal (see "Browser find-in-page" above), rather than merely hidden by CSS, screen readers skip it entirely, in both linear reading and virtual-cursor/browse-mode navigation, not just for sighted mouse/keyboard users. This also means the component never puts aria-hidden on content that could still receive real focus, an anti-pattern most automated audits (and screen readers) flag.

Accessible name includes the subheading and tag

heading, subheading, and a slotted/prop-driven tag all render as text inside the trigger <button>, so all of it is folded into the button's single accessible name. A screen reader announces them together as one string, not as a heading with a separate description. Keep subheading short for that reason. If it needs to be read as a distinct piece of information rather than appended to the name, don't rely on eun-collapse alone for that distinction.

No accessible name needed on the host

aria-label/aria-labelledby aren't needed on eun-collapse itself. The trigger's own visible heading text already serves as its accessible name, so there's nothing extra to wire up.

Heading level is opt-in

Set level (2-6) to wrap the trigger in a real <h2>-<h6> matching your page's own outline (e.g. several FAQ entries at level="3") so screen reader users can jump between them the same way they'd jump between any other headings on the page. Left unset by default, since the component has no way to know where it sits in your outline. Wrapping it in a heading unconditionally could just as easily produce a wrong or duplicate level.

Don't slot interactive content into heading/icon/tag/chevron

heading, icon, tag, and chevron all render inside the trigger's own <button>. A link, another button, or any focusable element slotted into one of them becomes interactive content nested inside interactive content, which is invalid per the HTML specification and unreliable across browsers and assistive technology (most browsers simply make the nested control unreachable by keyboard, while still visually present). Reserve those slots for non-interactive content only (icons, eun-tag, plain text or images) exactly like the built-in fallbacks they replace. Content in the default slot (the panel body) has no such restriction: it renders inside #panel, a plain sibling <div>, not inside any button. Real form controls, links, or any other interactive element are all fine there (see "Custom content" in the Examples tab). inert still reaches through the slot boundary onto that content exactly as it does for the rest of the panel. Anything slotted in is unfocusable and unclickable while closed, and becomes reachable again immediately once open, with no extra wiring needed on your part.

independent is presentation-only, with one implication worth knowing

independent only ever changes CSS (:host([independent]) selectors). It adds no ARIA state, no role, and no keyboard behavior, so it's safe to toggle purely for layout without touching anything else in this page. The one thing worth knowing goes the other way. The default flush shape (no independent) visually reads as "these collapses are one connected group", exactly the cue the "Exclusive (accordion)" example in the Examples tab relies on, but eun-collapse has no matching structural grouping of its own (no shared role="group", no <fieldset>). A sighted user gets that relationship for free from the shape. A screen reader user navigating by heading or by Tab only gets it if you also wrap the group in a <fieldset>/role="group" with an accessible label (or rely on consistent level headings to at least convey they sit at the same depth, per WCAG 1.3.1 Info and Relationships). Purely side-by-side collapses with independent set have no such relationship to convey in the first place, so nothing extra is needed there.

Disabled state

disabled sets the native disabled attribute directly on the trigger <button> (not a custom aria-disabled role), so it gets the browser's own disabled semantics for free: removed from the tab order, unclickable, and announced as disabled by every screen reader without any extra ARIA. Only its opacity is themeable via --collapse-disabled-opacity. The underlying semantics can't be overridden.

Visual and motion

Color contrast

The default background/text combination is built from this design system's own color tokens, already chosen to meet contrast minimums. A custom combination of --collapse-background/--collapse-color (closed, hover, or open) must still be checked against WCAG 1.4.3 Contrast (Minimum). See Color for the tokens that already meet it. --collapse-content-color needs the same check, independently. It controls the panel body's text against --collapse-background-open, a separate background/foreground pair from the trigger's own. Overriding one without the other is exactly how the default "Custom colors" example above would fail contrast on a dark --collapse-background-open if --collapse-content-color weren't also set.

Reduced motion

Respects prefers-reduced-motion. The open/close height animation, the chevron rotation, and the color transitions are all skipped entirely for users who've asked for reduced motion, satisfying WCAG 2.3.3 Animation from Interactions.

Reference links

WAI-ARIA APG: Disclosure Pattern
WCAG 4.1.2: Name, Role, Value
WCAG 1.3.1: Info and Relationships
WCAG 2.4.3: Focus Order
WCAG 1.4.3: Contrast (Minimum)
WCAG 2.3.3: Animation from Interactions
MDN: inert
MDN: hidden="until-found"