Behaviors
The kit ships 58 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 | — | ✓ |
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 | ✓ |
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.