JSCommands

An immutable sequence of browser commands which may bind server messages of type Msg.

The type is covariant so a command with no server message, including JS, composes with commands for any LiveView message type. Use a command with typed HTML event bindings such as on.click(command), or execute client-only commands from the server with ctx.client.exec. Class, attribute, and visibility mutations use the LiveView client's patch-aware operations, so their resulting DOM state is retained across server patches. Builders do not generally validate class names, attribute names, display values, or durations; invalid values retain the browser/client's behavior.

A command containing push must be rendered as an HTML event binding. Rendering gives each push a stable binding ID and registers its typed message. Encoding such a command directly, or sending it through ctx.client.exec, has no HTML binding scope and leaves the push unresolved; the encoded placeholder is not a usable server event binding.

Appends a command which adds whitespace-separated class names to the selected elements.

to defaults to the element executing the command. transition may be a class string or an (transition, start, end) tuple of class strings; "" requests no transition. time is the transition duration in milliseconds and defaults to 200. blocking defaults to true, so LiveView defers concurrent UI work for the transition; use false to let it run asynchronously.

Appends a command which dispatches a DOM event to the selected elements.

The LiveView client dispatches "click" as a MouseEvent and other names as a CustomEvent. detail is included in the event detail along with a client-supplied dispatcher reference. Events bubble by default. With blocking = true, the detail also contains done; the listener must eventually call it to release the blocked UI.

Appends a command which executes the encoded JS command stored in an HTML attribute.

The attribute is read from each selected element and executed with that element as its command source. A missing or empty attribute causes the LiveView client to report an error.

Appends a command which focuses the selected elements.

to defaults to the element executing the command.

Appends a command which focuses the first focusable descendant of each selected element.

The client prefers an interactive descendant and falls back to the first focusable one. to defaults to the element executing the command.

Appends a command which hides selected elements that are currently visible.

transition accepts a class string or an (transition, start, end) tuple; "" requests no transition. time is measured in milliseconds and defaults to 200. blocking defaults to true; false allows the timed transition to proceed without blocking other LiveView UI work. to defaults to the element executing the command.

Appends a command which preserves selected client-side attributes across future DOM patches.

Names may include the LiveView client's * wildcard syntax. Calling this command again replaces the ignored set for each target. It affects future patches only, so it cannot restore an attribute already changed during disconnected render. Although attrs defaults to an empty sequence, the current client expects an actual list; pass a non-empty sequence rather than relying on that default. to defaults to the element executing the command.

Appends a command which focuses the most recently pushed focus target, if one exists.

Appends a typed event push to the server.

Unlike Phoenix's string event API, event is the Scala message delivered by the rendered event binding. HTML rendering replaces it with a stable binding ID and registers the message under that ID. This widens the command's message type as needed. Multiple pushes in one command are registered independently and retain composition order.

target = DomSelector.current omits an explicit target, allowing the source element's phx-target and normal LiveView ownership rules to apply. An explicit selector overrides that target. The source receives the normal loading state; an explicit loading selector additionally applies the event's loading class and locks matching elements until the server acknowledges the push. pageLoading defaults to false; the option is encoded, but the currently supported Phoenix client does not observe its camel-case name, so setting it does not currently trigger page-loading lifecycle events.

A push must be attached to a typed HTML event binding such as on.click(JS.push(message)). Standalone JSON encoding and ctx.client.exec cannot allocate its binding ID and therefore leave an unresolved placeholder.

Appends a command which pushes a focus target onto the client's focus stack.

Pair this with popFocus to restore focus later. to defaults to the element executing the command.

Appends a live navigation to a typed location and pushes a browser history entry.

This changes LiveViews rather than patching the current one. Requiring LiveLocation keeps normal navigation tied to route-derived, encoded destinations; use pushNavigateUnsafe only when no typed location can represent the destination.

Builds a signal-backed command for a navigation destination.

Appends a live navigation to the raw href and pushes a browser history entry.

The string is passed through without route typing, validation, or normalization. "Unsafe" denotes that explicit escape from typed outbound navigation; it does not apply a different client navigation mechanism.

Builds a signal-backed command for a raw navigation destination.

Appends a live patch to a typed location and pushes a browser history entry.

A patch updates the current LiveView without replacing it. Use pushPatchUnsafe for raw destinations such as query-only references which cannot be represented by a full typed location.

Builds a signal-backed command for a patch destination.

Appends a live patch to raw href and pushes a browser history entry.

The string is passed through without route typing, validation, or normalization. This is the explicit escape hatch for destinations such as "?page=2".

Builds a signal-backed command for a raw patch destination.

Appends a command which removes attr from the selected elements.

The client keeps this attribute mutation across subsequent DOM patches. to defaults to the element executing the command.

Appends a command which removes whitespace-separated class names from selected elements.

to defaults to the element executing the command. transition may be a class string or an (transition, start, end) tuple of class strings; "" requests no transition. time is the transition duration in milliseconds and defaults to 200. blocking defaults to true, so LiveView defers concurrent UI work for the transition; use false to let it run asynchronously.

Appends a live navigation to a typed location and replaces the current history entry.

This changes LiveViews rather than patching the current one. Use replaceNavigateUnsafe only for a destination which cannot be represented by a LiveLocation.

Builds a signal-backed command for replacement navigation.

Appends a live navigation to raw href and replaces the current browser history entry.

The string is passed through without route typing, validation, or normalization.

Builds a signal-backed command for raw replacement navigation.

Appends a live patch to a typed location and replaces the current browser history entry.

Builds a signal-backed command for replacement patching.

Appends a live patch to raw href and replaces the current browser history entry.

The string is passed through without route typing, validation, or normalization.

Builds a signal-backed command for raw replacement patching.

Appends a command which sets an HTML attribute on the selected elements.

arg is the attribute name and value. The client keeps this attribute mutation across subsequent DOM patches. This changes an attribute, not a same-named DOM property. to defaults to the element executing the command.

Appends a command which shows selected elements that are currently hidden.

transition accepts a class string or an (transition, start, end) tuple; "" requests no transition. time is measured in milliseconds and defaults to 200. blocking defaults to true; false allows the timed transition to proceed without blocking other LiveView UI work. The default display request uses the client's normal display value (block, with table-row and table-cell handling); another value is sent explicitly. to defaults to the element executing the command.

Appends a command which toggles the visibility of selected elements.

in and out each accept a class string or an (transition, start, end) tuple; "" requests no classes for that direction. time is measured in milliseconds and defaults to 200. blocking defaults to true; false lets a timed transition run without blocking other LiveView UI work. The default display request uses the client's normal display value (block, with table-row and table-cell handling); another value is sent explicitly. to defaults to the element executing the command.

Appends a command which toggles an attribute on selected elements.

With the default empty altValue, the client sets name to value when absent and removes it when present. With a non-empty altValue, it toggles between value and altValue. to defaults to the element executing the command.

Appends a command which toggles whitespace-separated class names on the selected elements.

to defaults to the element executing the command. transition may be a class string or an (transition, start, end) tuple of class strings; "" requests no transition. time is the transition duration in milliseconds and defaults to 200. blocking defaults to true, so LiveView defers concurrent UI work for the transition; use false to let it run asynchronously.

Appends a temporary class transition to the selected elements.

A string supplies transition classes with empty start and end phases. A tuple supplies the (transition, start, end) class strings. Unlike the optional transitions on visibility and class commands, this command always sends a transition shape; callers should provide at least one non-empty class rather than relying on the "" default. time is measured in milliseconds and defaults to 200. blocking defaults to true; false lets the transition run without blocking other LiveView UI work. to defaults to the element executing the command.