Reference
The events Mero UI sends and acts on, the functions on window.MeroUI, and every data-mero-* attribute.
Events Mero sends
Each event bubbles, so you can listen on the component or on document.
mero:selection
Fires on the data-mero-listbox element when a person chooses an option. See List Box.
event.detail is { value, option }. value is the option’s data-value, or its text when that is absent. option is the chosen element.
mero:query
Fires on a remote combobox input when it needs fresh options, for example an arrow key after a failed request. Add it to hx-trigger next to input. See Autocomplete.
The event has no detail.
mero:kanban-move
Fires on a card after it moves to another lane. Requires mero-collections.js. See Kanban.
event.detail is { card, from, to }. from and to are the lanes’ data-lane values.
mero:reaction
Fires on a reaction button after its count and pressed state change. Requires mero-insights.js. See Emoji Reaction Button.
event.detail is { label, pressed }. label is the button’s data-label. pressed is the new state.
document.addEventListener("mero:kanban-move", (event) => {
const { card, from, to } = event.detail;
// Persist the move in your own service.
});Events Mero acts on
Send these from your server in an htmx trigger header, or dispatch them from a script. The object after the event name becomes event.detail.
mero:toast
Shows a notification. message is required. tone and duration match MeroUI.toast.
HX-Trigger: {"mero:toast":{"message":"Export ready","tone":"success"}}mero:form-saved
Requires mero-forms.js. Closes the dialog around the data-mero-form that received the event, returns focus and shows message as a success toast. Set target to a selector when the form is not the element that made the request.
HX-Reswap: none
HX-Trigger-After-Settle: {"mero:form-saved":{"message":"Saved"}}window.MeroUI
mero.js defines these once it has loaded.
MeroUI.open(dialog, { trigger })
Opens a <dialog> as a modal. Pass the element or its ID. Focus returns to trigger on close, by default the element focused when you call it.
MeroUI.close(dialog, { focus, value })
Closes an open dialog. focus overrides where focus returns. value becomes the dialog’s returnValue.
MeroUI.toast(message, { tone, duration })
Shows a notification. tone is accent, success, warning or danger. duration is in milliseconds, 4800 by default. Use 0 to keep it until dismissed.
MeroUI.init(root)
Sets up tabs, listboxes, comboboxes and auto-opening dialogs inside root. Mero calls it for every htmx swap. Call it yourself for markup you insert another way.
Attributes
Every data-mero-* attribute, grouped by the file that reads it. You write most of them in your templates. Mero sets the ones marked set by Mero, which you can use in selectors.
Core · mero.js
data-mero-open- On a button. The value is the ID of the
<dialog>to open as a modal. data-mero-close- On a control inside a dialog. Closes it. The value becomes the dialog’s
returnValue. data-mero-autoopen- On a dialog. Opens it as soon as it is on the page or swapped in.
data-mero-static- On a dialog. A click on the backdrop does not close it.
data-mero-toast- On a button. Shows the value as a notification on click.
data-mero-tone- With
data-mero-toast. One ofaccent,success,warningordanger. data-mero-toggle- On a button. Flips
aria-pressedon click. data-mero-remove- On a button inside
.mero-chip. Removes the chip and moves focus to a neighbour. data-mero-tabs- Root of a tab set. Selects tabs in the
role="tablist"inside and shows the matching panel. Also scopes IDs likedata-mero-scope. data-mero-tabs-readyset by Mero- On the tab root once a tab is selected.
data-mero-accordion- On the parent of
<details>elements. Only one stays open at a time. data-mero-radio-group- Around radios that sit outside a form. Repeated copies with the same
namestay independent. data-mero-radio-ownerset by Mero- On the hidden form Mero adds to own those radios.
data-mero-scope- On a repeated snippet or fragment. Mero renames duplicate IDs inside it and updates
for, ARIA,popovertarget,data-mero-openandhx-targetreferences to match. data-mero-listbox- On a
role="listbox". Adds arrow-key navigation and selection, and firesmero:selection. data-mero-combo- Root of a combobox. Wraps the
role="combobox"input and its options. data-mero-combo-remote- On the combobox root when the options come from your server. Mero then leaves filtering to the response.
data-mero-combo-status- Inside a combobox. The element that receives loading and error text.
data-mero-empty-option- On the option to show when nothing matches. It cannot be selected.
data-mero-activeset by Mero- On the option highlighted with the keyboard.
data-mero-combo-pendingset by Mero- On the combobox input while a request for options is in flight.
data-mero-combo-errorset by Mero- On the combobox input after a request for options failed.
data-mero-combo-dismissedset by Mero- On the combobox input after Escape, so a late response does not reopen the list.
data-mero-errorset by Mero- On the combobox status element while it shows an error.
data-mero-tooltip-belowset by Mero- On a tooltip placed below its anchor because there is no room above.
data-mero-tooltip-dismissedset by Mero- On a tooltip closed with Escape, until the pointer and focus leave it.
data-mero-pending- On any element. Shows a
.mero-indicatorinside it, as.htmx-requestdoes. data-mero-request- With a pending state. Sets a progress cursor on the element.
Forms · mero-forms.js
data-mero-form- On a form that htmx submits. Disables its submit buttons while the request runs, swaps in the replacement form on HTTP 422 and focuses the first invalid field.
data-mero-form-error- Inside the form. Receives the message when a request fails with a status other than 422. Send your own text in a
Mero-Form-Errorresponse header. data-mero-return-focus- On the form. Selector for the element to focus after
mero:form-saved. data-mero-fallback-focus- On the form. Selector to focus when the return-focus element is gone.
data-mero-close-all- On a form in a nested dialog. A save closes the parent dialogs too.
Gallery · mero-gallery.js
data-mero-slide- On each slide. Its value links the slide to a choice control.
data-mero-gallery-choice- On a radio or select whose value names a slide. Changing it shows that slide.
data-mero-prev- On a button. Goes to the previous slide.
data-mero-next- On a button. Goes to the next slide.
data-mero-gallery-label- Receives the current slide’s
data-labeltext. data-mero-gallery-link- On a link. Its
hreffollows the current slide’sdata-href. data-mero-hover-preview- On the gallery element. Hovering a choice with a mouse previews its slide.
data-mero-before- On the first image of an image diff. The slider clips this one.
Collections · mero-collections.js
data-mero-grid- Root of a data grid. Keeps the select-all checkbox, the selection count and the bulk action bar in step with the row checkboxes.
data-mero-grid-focus- On the grid in a server response. Names what to focus after the swap:
field,cancel,invalid,add,search,edit-IDordelete-ID. Mero removes it once used. data-mero-agenda- Root of an agenda. Restores focus after a swap from its
data-agenda-focusvalue, and swaps an error response only on HTTP 422. data-mero-load-supersededset by Mero- On a grid or agenda mount when the person acted before its first refresh returned. That refresh is then discarded.
data-mero-kanban- Root of a board. Cards move between its
data-lanecolumns by drag or by the Move to menu, and firemero:kanban-move. data-mero-hover-card- Around a trigger and its preview panel. Opens the panel on hover or focus.
data-mero-toc- Root of a floating table of contents. Its links scroll the content and mark the current section.
data-mero-place-map- Root of a map. Choosing a
data-placepin shows the matchingdata-place-detail. data-mero-widget- Around a checklist. Updates its
<progress>and<output>as boxes are checked.
Insights · mero-insights.js
data-mero-chart- On a chart figure. The chart type, used to style the legend.
renderChartwrites it. data-mero-plot-value- On each chart mark. The text announced and shown when the mark has focus or hover.
data-mero-series- On each chart mark. Arrow up and down move between series at the same category.
data-mero-plot-readout- Receives the text of the active mark for assistive technology.
data-mero-plot-tooltip- The tooltip positioned at the active mark.
data-mero-copy- On a button in a code block or chat message. Copies the code or the message text.
data-mero-copy-labelset by Mero- On a copy button. Its original label, restored after “Copied”.
data-mero-message-text- Inside a chat message. The text a copy button copies.
data-mero-reaction- On a reaction button. Toggles
aria-pressed, updates the count and firesmero:reaction. data-mero-count- Inside a reaction button. The element holding the count.
data-mero-pressable- On a button. Flips
aria-pressedand swaps its star icon. data-mero-press-icon- Inside a pressable button. The element holding the icon.
data-mero-suggest- On a button in a prompt form. Puts its text into the form’s textarea.
data-mero-compose- On a chat form. Shows progress in its status element, keeps the draft when sending fails and blocks error swaps.
data-mero-chat-status- Inside a chat form. Receives “Preparing reply…” and send errors.
data-mero-topic- On each conversation link in a chat inbox. Its value is the conversation’s ID.
data-mero-current-topic- In a thread response. Marks the link with the same value as current.
data-mero-report-status- In a chat inbox, Markdown editor or report filter. Receives the result of the last update.
Workspace · mero-workspace.js
data-mero-ws-shell- Root of an app shell. A
data-mero-ws-openbutton inside opens its dialog. data-mero-ws-open- On a button inside a shell, command menu or emoji picker. Opens that component’s dialog.
data-mero-ws-command- Root of a command menu. Cmd or Ctrl and K opens it, and typing filters its actions.
data-mero-ws-emoji- Root of an emoji picker. Choosing an emoji fills its hidden input and closes the dialog.
data-mero-ws-context- Root of a context menu. A right click, the menu key or Shift and F10 on a row opens its
role="menu". data-mero-ws-context-open- On the button that opens the same context menu.
data-mero-ws-action- On a context menu item. Only
pinhas built-in behavior: it toggles the pinned state. data-mero-ws-editor- On a rich text form. Copies the formatted text into its
runsandbodyfields. Buttons withdata-formatapply formatting. data-mero-ws-number- Around a number input. Buttons with
data-stepstep the value and disable at the limits. data-mero-ws-upload- On an upload form. Shows the chosen file name and ignores the response for a file that has since been replaced.
data-mero-ws-wizard- On a multi-step form. Shows one panel at a time.
data-mero-ws-next- On the wizard’s button to the next step.
data-mero-ws-back- On the wizard’s button to the previous step.
data-mero-ws-finish- On the wizard’s submit button. Shown on the last step only.
data-mero-ws-review- In the wizard. Receives a summary of the
projectandaccessfields. data-mero-ws-split- Root of a resizable split. The separator inside resizes it by drag or arrow keys.
data-mero-ws-snap- With
data-mero-ws-split. Adds a snap point learned from the widths the person has chosen. data-mero-ws-snap-key- With a snapping split. A name under which the width is remembered for the browser session.
data-mero-ws-split-readyset by Mero- On a snapping split once it is set up.
data-mero-ws-draggingset by Mero- On the split handle during a drag.
data-mero-ws-snappedset by Mero- On the split handle while it rests on the snap point.
data-mero-ws-widthset by Mero- On the split handle. The current width in pixels, shown by the stylesheet.
Composition · mero-composition.js
data-mero-text-cycle- Around rotating text. Buttons with
data-cycle-nextanddata-cycle-playstep or auto-advance itsdata-cycle-itemelements. data-mero-theme-scope- On a section. Receives the theme chosen in the picker inside it.
data-mero-theme-picker- On a select or radio. Its value becomes the scope’s
data-theme. data-mero-cutoff-hour- Around a
<time>. Counts down to that hour, 0 to 23 in UTC. data-mero-check-form- On the catalog’s validation demo form. It reports a fixed message and is not meant for your app.