htmx Interactivity

htmx Interactivity

Use this skill when htmx handles server trips but the page still needs local browser behavior. Keep the ownership line explicit so server-rendered HTML and client-side state do not fight each other.

Ownership Rules

• htmx owns server requests, fragment swaps, history updates, and server-triggered events.
• The server owns durable state, validation, permissions, and canonical HTML.
• Alpine or plain JavaScript owns local state such as menu open/closed, tabs, disclosure state, temporary filters, focus helpers, and small transitions.
• _hyperscript is best for short event-driven behaviors attached to markup.
• Do not mirror the same durable state in both server data and a client store unless there is a reconciliation plan.

Use Alpine When

• A component has local state that changes without a server request.
• You need a dropdown, popover, modal shell, tab set, disclosure, or preview toggle.
• You need to coordinate htmx lifecycle events with UI state.
• The state naturally belongs near the markup and is simple enough to read inline.

Keep persistent Alpine state outside htmx targets that will be replaced. If htmx swaps the element that owns x-data, that state resets.

Use _hyperscript When

• The behavior is a small event script, such as adding a class, waiting, then removing it.
• The script reads like a local interaction, not application business logic.
• The team accepts _hyperscript syntax as part of the template layer.

Avoid _hyperscript for complex state machines, security-sensitive logic, large data transforms, or behavior that needs substantial tests.

Event Boundary Pattern

Use events as the bridge between server results and local browser state:

1. The htmx request submits to the server.
2. The server returns HTML and optionally triggers a domain event.
3. Alpine, _hyperscript, or plain JavaScript listens for the event.
4. Local UI state updates, such as closing a modal or focusing a saved row.

Prefer domain event names over implementation names: