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.