Skip to content

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.

JavaScript
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.

Response headers
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.

Response headers
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 of accent, success, warning or danger.
data-mero-toggle
On a button. Flips aria-pressed on 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 like data-mero-scope.
data-mero-tabs-ready set 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 name stay independent.
data-mero-radio-owner set 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-open and hx-target references to match.
data-mero-listbox
On a role="listbox". Adds arrow-key navigation and selection, and fires mero: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-active set by Mero
On the option highlighted with the keyboard.
data-mero-combo-pending set by Mero
On the combobox input while a request for options is in flight.
data-mero-combo-error set by Mero
On the combobox input after a request for options failed.
data-mero-combo-dismissed set by Mero
On the combobox input after Escape, so a late response does not reopen the list.
data-mero-error set by Mero
On the combobox status element while it shows an error.
data-mero-tooltip-below set by Mero
On a tooltip placed below its anchor because there is no room above.
data-mero-tooltip-dismissed set by Mero
On a tooltip closed with Escape, until the pointer and focus leave it.
data-mero-pending
On any element. Shows a .mero-indicator inside it, as .htmx-request does.
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-Error response 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-label text.
data-mero-gallery-link
On a link. Its href follows the current slide’s data-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-ID or delete-ID. Mero removes it once used.
data-mero-agenda
Root of an agenda. Restores focus after a swap from its data-agenda-focus value, and swaps an error response only on HTTP 422.
data-mero-load-superseded set 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-lane columns by drag or by the Move to menu, and fire mero: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-place pin shows the matching data-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. renderChart writes 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-label set 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 fires mero:reaction.
data-mero-count
Inside a reaction button. The element holding the count.
data-mero-pressable
On a button. Flips aria-pressed and 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-open button 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 pin has built-in behavior: it toggles the pinned state.
data-mero-ws-editor
On a rich text form. Copies the formatted text into its runs and body fields. Buttons with data-format apply formatting.
data-mero-ws-number
Around a number input. Buttons with data-step step 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 project and access fields.
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-ready set by Mero
On a snapping split once it is set up.
data-mero-ws-dragging set by Mero
On the split handle during a drag.
data-mero-ws-snapped set by Mero
On the split handle while it rests on the snap point.
data-mero-ws-width set 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-next and data-cycle-play step or auto-advance its data-cycle-item elements.
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.