Modals, Tabs & Accordions

Components other frameworks spend hundreds of kilobytes of JavaScript on. Here the browser does it: a native <dialog>, <details>, and hidden radio fields. Ready-made blocks are in the examples.

1. How much JavaScript each one needs

This is the most important table on this page. Four out of seven components don't need any script at all - they work even if JS never loads.

Component Mechanism JavaScript
.accordion-item <details> zero
.tabs Hidden input[type="radio"] zero
.tooltip-element The data-tooltip attribute + CSS zero
.tooltip-popover Popover API (popover="hint") + Anchor Positioning auto-loaded module
.grid-expand Animated grid-template-rows zero
.popover-context Popover API + Anchor Positioning flip only
.modal-dialog Native <dialog> one line
.toast Popover API required

2. Modals

The base is a native <dialog>. The browser gives you four things for free that JS libraries need separate code for: a dimmed backdrop (::backdrop), a focus trap (Tab can't escape the modal), closing via the Esc key, and promotion to the top layer, so no z-index or overflow can cover it.

Action How
Opening .showModal() on the element. This is the only place where the modal needs JS - use .showModal(), not .show(), see pitfall #1.
Closing with a button A button inside <form method="dialog">. The browser closes it itself - zero script.
Closing by clicking the backdrop Handled globally by molique-script.js, for every modal on the page.
Closing with the Esc key Native. Nothing to do.
<button onclick="document.getElementById('myModal').showModal()">Open</button>

<dialog id="myModal" class="modal-dialog">
  <div class="card">
    <div class="card-header">Title</div>
    <div class="card-body">Content…</div>
    <div class="card-footer">
      <!-- Native closing, no JS -->
      <form method="dialog">
        <button class="btn btn-secondary">Close</button>
      </form>
    </div>
  </div>
</dialog>
Class What it does
.modal-dialog A window centered on screen. The base variant.
.modal-sm A narrower window - short messages.
.modal-context A side panel on desktop, and a bottom sheet on the phone. The same markup.
.modal-confirm A confirmation window - a centered icon and two buttons.
.modal-confirm-icon A large icon above the question. Set the color via a text class, e.g. .text-danger for a deletion.
.modal-action-list A vertical list of actions in a side panel.
.modal-action-btn A single action in the list.
.modal-divider A divider between action groups.
.is-fallback The safety net, set by JS. After every opening, molique-modal-guard.js (loaded automatically when the page has a .modal-dialog) checks whether the window actually painted. If after a second look it still has no size or is transparent, it gets this class and is redrawn as a plain block, with no flex, percentages or animation. Guards against “dimmed screen, no window”, where the page stops responding. You never write it yourself.
.modal-close-btn The × in the corner. Put it inside a <form method="dialog"> so it works without a script.

3. Accordions

Every item is a <details>. Expanding, keyboard support, and text search inside collapsed content (Ctrl+F opens the right section) are all native.

To keep only one item open at a time, give them all the same name attribute - the browser takes care of the rest, exactly like a radio field group.

<div class="accordion">
  <details class="accordion-item" name="faq" open>
    <summary class="accordion-header">First question</summary>
    <div class="accordion-body">Answer…</div>
  </details>
  <details class="accordion-item" name="faq">
    <summary class="accordion-header">Second question</summary>
    <div class="accordion-body">Answer…</div>
  </details>
</div>
Class On What it does
.accordion <div> Wrapper for the group - border and rounding for the whole thing.
.accordion-item <details> A single item.
.accordion-header <summary> A clickable bar with an arrow. Fits several elements side by side (e.g. a badge and text) - they'll stay left-aligned.
.accordion-body <div> The expandable content.

Expanding anything else: .grid-expand

Animating height from zero to "whatever it turns out to be" is impossible in pure CSS - height: auto can't be animated. The trick is to animate grid-template-rows from 0fr to 1fr. Useful anywhere <details> doesn't fit: an expandable table row, a "show more" under a description.

Two elements: .grid-expand is the animated container, .grid-expand-inner wraps the content (without it there's nothing to compress). It opens three different ways - pick one depending on what controls the expansion.

Trigger When
.is-open You add and remove the class yourself - e.g. from your own JS.
details[open] .grid-expand sits inside a native <details> - zero JS.
.form-switch + .grid-expand An iOS-style switch right before the container (a sibling, not nested) - zero JS.
<div class="grid-expand is-open">
  <div class="grid-expand-inner">Content that expands</div>
</div>

The third variant - a switch (full description in the forms documentation) revealing a field below, a common pattern in forms ("Send notifications?" → an email address field):

<label class="form-switch">
  <input type="checkbox" class="form-switch-input">
  <span class="form-switch-label">Send email notifications</span>
</label>

<!-- Sibling of the switch, NOT inside the same <label> ->
     a click in the content below would otherwise also toggle the switch -->
<div class="grid-expand">
  <div class="grid-expand-inner">
    <input type="email" class="input" placeholder="Email address">
  </div>
</div>

The opposite case: content visible while the switch is off. .grid-expand-unchecked is open by default and collapses when a .form-switch standing earlier in the same parent is turned on, even with another panel between them:

<div class="grid-expand grid-expand-unchecked">
  <div class="grid-expand-inner">Visible while the switch is off</div>
</div>

4. Tabs

Tabs are a radio field group in disguise. A hidden input[type="radio"] holds the state, and the visible tab is a <label> pointing at it. Since only one radio field in a group can be checked, you get mutual exclusion for free - and, thanks to being hidden with the clip technique instead of display: none, keyboard arrow-key support too.

<div class="tabs">
  <!-- State: every input MUST share the same name -->
  <input type="radio" name="my-tabs" id="tab-1" class="tab-input" checked>
  <input type="radio" name="my-tabs" id="tab-2" class="tab-input">

  <div class="tabs-header">
    <label for="tab-1" class="tab-label">First</label>
    <label for="tab-2" class="tab-label">Second</label>
  </div>

  <div class="tabs-content">
    <div class="tab-pane">First content</div>
    <div class="tab-pane">Second content</div>
  </div>
</div>
Class What it does
.tabs The component's wrapper.
.tab-input The hidden radio field holding state. Shared name within one set of tabs.
.tabs-header The bar with the tabs.
.tab-label The visible tab. for must point at the matching field's id.
.tabs-content The panel container.
.tab-pane A content panel. The order of panels must match the order of the radio fields - see pitfall #3.
.tabs-pill An appearance variant: tabs as pills instead of an underline.
.tabs-pill without .tabs-content A switcher on its own, with no panels: a filter or navigation between pages. Its width then follows the pill, so neighbours in a row are not pushed away. With panels, .tabs takes the full width as before.
.tabs-pill-indicator The sliding background of the active pill. Its width is calculated from the --tab-count variable - set it to the number of tabs.

5. Toasts

The only component on this page that requires JavaScript - a notification by its nature appears in response to an event, so it can't sit in the HTML. You don't build the markup yourself; you call a function.

MoliqueToast.show({
  message: 'Changes saved',
  type: 'success',        // success | danger | warning | info
  position: 'top-right',  // top-left | top-center | top-right
                          // bottom-left | bottom-center | bottom-right
  duration: 4000,         // ms
  html: false             // true = message as HTML (see the table)
});
Parameter Default Notes
message 'Notification' The message content - inserted as text (since v1.7.37). Markup shows literally, so text from the URL, a server response or a form cannot run code.
type 'info' An unknown value silently falls back to info instead of breaking the page.
position 'top-right' The container for a given corner is created on its own on first use.
duration 4000 Time in milliseconds.
html false Only true turns on HTML in the message. Use it only with text written entirely by the page code - never with anything that came from a user or a server.

Toast classes and PurgeCSS

The classes .toast-success, .toast-top-right, and the rest don't appear in your HTML - the script adds them. PurgeCSS will consider them dead code and strip them, leaving notifications without any style. That's why molique ships a ready-made safelist; details in PurgeCSS & the safelist.

Class What it does
.toast-container The screen-corner container; created by the script.
.toast A single notification.
.toast-progress A bar counting down to dismissal. The toastProgressAnim animation also needs to be on the safelist.
.toast-success, .toast-danger, .toast-warning, .toast-info Colors according to the type parameter.
.toast-top-left, .toast-top-center, .toast-top-right, .toast-bottom-left, .toast-bottom-center, .toast-bottom-right The six positions per the position parameter.
.is-closing The dismissing state; applied by the script.

6. Tooltips and context menus

Tooltip

The content sits in the data-tooltip attribute, and CSS draws the bubble. Zero script and zero extra elements in the tree.

<span class="tooltip-element" data-tooltip="Explanation">Hover me</span>

A short label stays on one line, and longer text wraps at --tooltip-max-width (280px by default), centred. For a full sentence (why a field is locked, where a number comes from) add .tooltip-element-wide - several lines of a sentence read better left-aligned:

Why can I not change this?

<span class="tooltip-element tooltip-element-wide"
      data-tooltip="This field is locked because the order has already been sent to the warehouse.">Why can I not change this?</span>

Near the edge of a clipping container a centred bubble loses part of its content with no sign of it. A trigger near the left edge (the first column of a form or a table) takes .tooltip-element-start, one near the right edge .tooltip-element-end. Both combine with .tooltip-element-bottom and .tooltip-element-wide:

Hover me

<span class="tooltip-element tooltip-element-start" data-tooltip="The bubble starts at the left edge of the trigger.">Hover me</span>

A tooltip nothing can clip

.tooltip-element draws its bubble as a pseudo-element inside the trigger, so every ancestor with overflow cuts it off: .table-wrapper, .card, an accordion, the body of a modal. In those places use .tooltip-popover: a separate element with the popover="hint" attribute, which lands in the top layer once open. The trigger points at it through aria-describedby - the only link, so without that attribute nothing opens, and a screen reader always gets the description.

Order Status Actions
#1042 In the warehouse
<button type="button" class="btn-action" aria-describedby="tip-locked">Edit</button>

<div id="tip-locked" class="tooltip-popover" popover="hint" role="tooltip">
  Editing is locked because the order has already been sent out.
</div>

The bubble opens on hover (after 150 ms, so a pointer passing over lights nothing up), at once on keyboard focus and on touch. It closes when the pointer leaves (the bubble itself can be hovered to finish reading), on Esc, when focus moves away and on a tap elsewhere. Only one is open at a time. A popover does not react to hover by itself, so js/modules/molique-tooltip-popover.js does the work, auto-loaded when the page has a .tooltip-popover. The module is delegated, so rows added later (AJAX) need no re-initialisation. Since 1.7.41 the autoloader also brings the module in when the first .tooltip-popover reaches the page later.

The bubble sits above the trigger and, when there is no room, flips below it or slides sideways. Its width goes up to --tooltip-max-width, so a short label stays on one line and a sentence wraps with no separate variant. There is no arrow, because after a flip it would point the wrong way. popover="hint" (Chrome/Edge 133+) keeps the bubble from closing an open menu. A browser that does not know that value treats it as manual - the bubble works the same, because the module does the closing anyway. Without Anchor Positioning the module places the bubble against the window itself and closes it on scroll. Opening from code: MoliqueTooltipPopover.show(trigger) and MoliqueTooltipPopover.hide().

Context menu

A small menu that anchors itself to its trigger button. Built on the Popover API and Anchor Positioning, so it lands in the top layer - neither a table's overflow nor a card can clip it. JavaScript's only job here is checking whether the menu would overflow the bottom edge of the window, and flipping it above the button when it would (.is-flipped).

Class What it does
.tooltip-element An element with a bubble. Requires the data-tooltip attribute.
.tooltip-element-wide The full-sentence variant: aligns the wrapped text left. Every bubble wraps at --tooltip-max-width (280px by default) since 1.7.34.
.tooltip-popover A top-layer bubble no overflow can clip. An element with popover="hint", role="tooltip" and an id, named by the trigger's aria-describedby.
.tooltip-popover-bottom Below the trigger by default, above it only when there is no room.
.popover-context A menu with a popover attribute and its own id.
.popover-action-btn A menu item.
.is-flipped The menu flipped above the button when there's no room below. Applied by JS.

7. Pitfalls

1 .show() instead of .showModal()

Both methods open a <dialog>, but only .showModal() turns it into a modal. After .show() there's no dimmed backdrop, Esc doesn't close it, and focus can freely escape onto the content underneath - for a keyboard user, the window becomes a trap with no way out.

myDialog.show();       // WRONG - a plain window with no backdrop, no Esc
myDialog.showModal();  // RIGHT
2 A close button outside <form method="dialog">

It's the form itself that closes the modal natively. A button placed next to it does nothing until you add JS handling for it. This also applies to the × (.modal-close-btn) in the corner.

3 Mismatched order of tabs and panels

CSS links a radio field to its panel by position, not by name - the third checked field shows the third .tab-pane. Placing a panel in a different order than the inputs, or inserting something between them, will make the tabs show someone else's content.

A second variant of the same mistake: two sets of tabs on one page sharing the same name. Clicking one switches both.

4 Unstyled toasts after enabling PurgeCSS

A classic symptom: everything works locally, and after deployment the notifications are colorless white rectangles with a progress bar frozen in place. The reason is always the same - the toast-* classes are added by JS, so PurgeCSS never sees them in the files and strips them. Hook up the provided safelist.

5 Animating height instead of .grid-expand

height: auto can't be animated, so the typical workaround is measuring the height in JS and writing it in pixels. Besides the extra code, this triggers a layout recalculation on every frame. .grid-expand animates grid-template-rows and doesn't need to know the target height.

6 .grid-expand inside <label class="form-switch">

The "switch reveals content" pattern requires .grid-expand to be a sibling of .form-switch, not its child. The whole <label> forwards clicks to its own <input> - putting .grid-expand inside it means a click anywhere in the revealed content (e.g. in a form field) also toggles the switch.

8. Related pages

Standard modal

Press Esc or click outside the window - either one closes it, with nothing extra to add.