Behaviors
The kit ships 64 small behaviors. All of them are idempotent, return an
uninstaller, and — with the single exception of installChart() — are
auto-installed by the zero-config
@hypermedia-components/core/behaviors entry, which also picks up
content swapped in by htmx. Import them individually only when you
bundle selectively.
// Everything at once (what the CDN bundle does):import '@hypermedia-components/core/behaviors';
// Or pick and choose:import { installTabs, installToast } from '@hypermedia-components/core';installTabs();installToast();Two columns need a definition. Attributes lists the markup you (or
the server fragment) write to opt in to or configure the behavior — not
the state attributes the behavior itself writes at runtime
(data-active, aria-invalid, …). Where a component-bound behavior has
many options, only the most important are shown (“…”) and the page
linked in Powers has the full list. Events lists the hc:* events
the behavior dispatches; “—” means none.
Actions & forms
Section titled “Actions & forms”| Behavior | Powers | Attributes | Events | Auto-init |
|---|---|---|---|---|
installValidation() |
Native-validation wiring for fields (blur/submit validation, message slots). | native constraint attributes (required, pattern, …) |
— | ✓ |
installFieldErrors() |
Server-driven inline errors — the field-errors recipe’s 422 fragment contract. | data-hc-field-errors, data-field, data-message-key (server-written) |
— | ✓ |
installShowWhen() |
Conditional field visibility — the conditional-fields recipe. | data-hc-show-when, data-hc-show-switch, data-hc-show-src |
— | ✓ |
installFormat() |
Grouped numeric display with a raw wire value — input. | data-hc-format, data-decimals, data-locale |
— | ✓ |
installNormalize() |
IME fullwidth / kana normalization on commit — input. | data-hc-normalize |
— | ✓ |
installMask() |
Declarative fixed-format masks (postal-jp, #/a/A/* patterns) — input. |
data-hc-mask, data-hc-mask-submit |
— | ✓ |
installSubmitOnChange() |
A control that is the action posts its form on change (or on the event the value names, e.g. hc:otpcomplete) — switch, input OTP. Exempt when htmx already drives the form on change. |
data-hc-submit-on-change |
— | ✓ |
installSubmitOnEnter() |
Enter sends, Shift+Enter breaks the line, an IME-confirming Enter is ignored — the chat-messages recipe’s composer. | data-hc-submit-on-enter |
— | ✓ |
installCount() |
A character count next to a bounded field — input: used / max from maxlength or a soft limit, near / over states, live outputs updated after a typing pause. |
data-hc-count, data-hc-count-max |
— | ✓ |
installSelectAll() |
A master checkbox for a checklist — checkbox: sets every enabled member, mirrors them back as checked / clear / indeterminate. | data-hc-select-all |
— | ✓ |
installMultiValue() |
One control, many values on the wire — a pasted list of identifiers becomes repeated params (input). | data-hc-multi (lines / commas) |
— | ✓ |
installRangeValue() |
Two controls, one range param on the wire — a date period leaves as f-ship=A..B (datagrid-filter). |
data-hc-range, data-hc-range-from, data-hc-range-to |
— | ✓ |
installSortList() |
The sort control’s ordered keys as one param — sort=-ship,order (datagrid-sort). |
data-hc-sort-list, data-hc-sort-key, data-hc-sort-dir-prefix |
— | ✓ |
installRowLink() |
Enter opens the record a row is about — the identity cell’s link (row-detail). | data-hc-row-link |
— | ✓ |
installDirtyGuard() |
Unsaved-changes guard — the unsaved-changes recipe. | data-hc-dirty-guard (state: data-dirty) |
hc:dirtychange |
✓ |
installSessionExpiry() |
401 → login dialog → request replay — the session-expiry recipe. | data-hc-session-expiry |
consumes hc:sessionrenewed |
✓ |
installNetworkRetry() |
No-answer failures (offline / timeout) → a retry alert with a working Retry — the network-retry recipe. | data-hc-network-retry (+ -message / -label overrides) |
listens to htmx:sendError / htmx:timeout |
✓ |
installTime() |
Client-side <time> localization (relative / absolute) — i18n. |
data-hc-time, data-hc-time-style |
— | ✓ |
installSortable() |
Pointer + keyboard list reordering — the sortable recipe. | data-hc-sortable, data-hc-sortable-handle, data-hc-sortable-id |
hc:sortchange |
✓ |
installCombobox() |
Combobox keyboard, filtering, ARIA. | data-remote, data-allow-create, data-value, … |
hc:comboboxselect |
✓ |
installMulticombobox() |
Multicombobox tags, keyboard, ARIA. | data-name, data-allow-create, data-value, … |
hc:multicomboboxchange |
✓ |
installInputOtp() |
Input OTP per-slot editing. | data-length, data-pattern, data-groups |
hc:otpchange, hc:otpcomplete |
✓ |
installPasswordToggle() |
The input-group password reveal. | data-hc-password-toggle, data-hc-label-show / data-hc-label-hide |
— | ✓ |
installSlider() |
Slider fill + value output sync. | — | — | ✓ |
installRange() |
Range dual-thumb clamping + fill. | — | hc:rangechange |
✓ |
installCalendar() |
Calendar grid, keyboard, selection. | data-value, data-min / data-max, data-mode, … |
hc:calendarchange, hc:calendarrangechange |
✓ |
installDropzone() |
Dropzone drag-over state + file list. | — | — | ✓ |
installUploadProgress() |
Driving a <progress> from htmx upload events — the file-upload recipe. |
data-hc-upload-progress |
— | ✓ |
installCodeEditor() |
The editable code field: gutter, live highlight (data-lang). |
data-editable, data-gutter, data-lang |
— | ✓ |
Navigation & command
Section titled “Navigation & command”| Behavior | Powers | Attributes | Events | Auto-init |
|---|---|---|---|---|
installTabs() |
Tabs roving focus + panel switching. | data-activation, data-orientation, data-overflow |
hc:tabactivated |
✓ |
installToggleGroup() |
Toggle group single/multiple selection + roving focus. | data-type, data-value, data-name |
hc:togglegroupchange |
✓ |
installToolbar() |
Toolbar single-Tab-stop arrow-key navigation (APG pattern). | role="toolbar", aria-orientation |
— | ✓ |
installMenu() |
Menu keyboard pattern, anchoring, ARIA. | popover + popovertarget (trigger) |
hc:menuselect |
✓ |
installMenubar() |
Menubar across-menu arrow keys. | role="menubar", popovertarget |
hc:menuselect (from its menus) |
✓ |
installNavmenu() |
Navigation menu panels. | data-hc-navmenu-trigger, aria-controls |
— | ✓ |
installContextMenu() |
Context menu right-click opening. | data-hc-context-menu |
hc:menuselect |
✓ |
installCommand() |
Command filtering + ranking + keyboard. | data-hotkey, data-filter, data-value |
hc:commandselect |
✓ |
installTree() |
Tree ARIA roles + expand/collapse. | aria-expanded (declares a branch), data-hx-get (lazy) |
hc:treeexpand |
✓ |
installSpy() |
TOC scrollspy (aria-current tracking). |
data-hc-spy |
— | ✓ |
installNavCurrent() |
Marking the current nav link after boosted navigations (shell). | data-hc-nav-current |
— | ✓ |
installShell() |
Shell sidebar collapse + persistence. | data-hc-shell-toggle, data-collapsible, data-persist, … |
— | ✓ |
Overlays & feedback
Section titled “Overlays & feedback”| Behavior | Powers | Attributes | Events | Auto-init |
|---|---|---|---|---|
installPopover() |
Popover anchoring + placement fallback. | data-side, data-align, data-arrow |
— | ✓ |
installTooltip() |
Tooltip show/hide + anchoring. | aria-describedby (trigger), data-side, data-align |
— | ✓ |
installHovercard() |
Hovercard intent delays + anchoring. | aria-describedby (trigger), data-side, data-align |
— | ✓ |
installDrawer() |
Drawer drag-to-dismiss. | data-side |
— | ✓ |
installToast() |
Toast region: hc:toast events, stacking, update-by-id, actions. |
data-hc-toast-region, data-position, data-limit |
hc:toast (listens) |
✓ |
installConfirm() |
The shared confirm dialog — confirm-action recipe (data-hc-confirm). |
data-hc-confirm, data-hc-confirm-title, data-hc-confirm-variant, … |
hc:confirmed |
✓ |
installRemoteDialog() |
Server-rendered dialogs — the remote-dialog recipe. | data-hc-remote-dialog-root |
— | ✓ |
installCloseDialog() |
Closing a dialog after a successful htmx request (data-hc-close-dialog-on-success). |
data-hc-close-dialog-on-success |
— | ✓ |
installClosePopover() |
The popover equivalent (data-hc-close-popover-on-success) — see the filter-popover recipe. |
data-hc-close-popover-on-success |
— | ✓ |
Data display
Section titled “Data display”| Behavior | Powers | Attributes | Events | Auto-init |
|---|---|---|---|---|
installDatagrid() |
Datagrid keyboard grid, sort/resize/edit/detail events. | data-sortable, data-editable, data-resizable, data-frozen, … |
hc:datagridsort, hc:datagridselectionchange, … (7 — see page) |
✓ |
installDatagridActions() |
The datagrid selection actions bar — datagrid-bulk-actions recipe. | data-hc-datagrid-actions, data-hc-datagrid-count |
— | ✓ |
installCarousel() |
Carousel active tracking, dots, keyboard. | data-autoplay, data-hc-carousel-prev / -next / -dots |
hc:carouselchange |
✓ |
installSplitter() |
Splitter drag + keyboard resize + persistence. | data-orientation, data-value, data-persist, … |
hc:splitterchange |
✓ |
installAvatar() |
Avatar image-error → initials fallback. | data-delay |
hc:avatarstatechange |
✓ |
installSparkline() |
Sparkline drawing from data-values. |
data-values, data-area, data-min / data-max |
— | ✓ |
installChatScroll() |
Chat transcript stick-to-bottom (stops following while the reader scrolls up). | — | — | ✓ |
installChart() |
Chart rendering via Observable Plot. | data-hc-chart, data-mark, … |
— | Opt-in — needs the @observablehq/plot peer; never bundled. |
Platform glue
Section titled “Platform glue”| Behavior | Powers | Attributes | Events | Auto-init |
|---|---|---|---|---|
installCopy() |
Clipboard buttons (data-hc-copy) — the copy recipe. |
data-hc-copy, data-hc-copy-text, data-hc-copy-ok |
hc:copied |
✓ |
installPrint() |
A Print button that calls window.print() with no inline script — print. |
data-hc-print |
— | ✓ |
installInvokerCommands() |
Feature-detected fallback for commandfor + command="show-modal" / "close" on engines below Baseline 2025 — dialog, browser support. Installs nothing on a native engine. |
commandfor, command |
— | ✓ |
installThemeToggle() |
The light/dark toggle button (theming). | data-hc-theme-toggle, data-persist |
hc:themechange |
✓ |
installCsrfHeader() |
Adding the CSRF header from meta[name="csrf-token"] to every htmx request (htmx guide). |
meta[name="csrf-token"] + data-header |
— | ✓ |
installSseDispatch() |
Bridging SSE messages into DOM events — the sse-updates / sse-toast recipes. | data-hc-sse-dispatch, data-sse-swap |
the names listed in data-sse-swap |
✓ |
Related
Section titled “Related”- Installation → Behaviors — bundles, idempotency, uninstalling.
- Fundamentals — the conventions every behavior follows.