Phoenix.LiveView.JS (Phoenix LiveView v0.17.5) View Source
Provides commands for executing JavaScript utility operations on the client.
JS commands support a variety of utility operations for common client-side needs, such as adding or removing css classes, showing or hiding content, and transitioning in and out with animations. While these operations can be accomplished via client-side hooks, JS commands are DOM patch aware, so operations applied by the JS APIs will stick to elements across patches from the server.
In addition to purely client-side utilities, the JS command incluces a
rich push API, for extending the default phx- binding pushes with
options to customize targets, loading states, and additional payload values.
Enhanced Push Events
The push/3 command allows you to extend the built-in pushed event handling
when a phx- event is pushed to the server. For example, you may wish to
target a specific component, specify additional payload values to include
with the event, apply loading states to external elements, etc. For example,
given this basic phx-click event:
<div phx-click="inc">+</div>Imagine you need to target your current component, and apply a loading state to the parent container while the client awaits the server acknowledgement:
alias Phoenix.LiveView.JS
<div phx-click={JS.push("inc", loading: ".thermo", target: @myself)}>+</div>Push commands also compose with all other utilities. For example, to add a class when pushing:
<div phx-click={
JS.push("inc", loading: ".thermo", target: @myself)
|> JS.add_class(".warmer", to: ".thermo")
}>+</div>Client Utility Commands
The following utilities are included:
add_class- Add classes to elements, with optional transitionsremove_class- Remove classes from elements, with optional transitionsshow- Show elements, with optional transitionshide- Hide elements, with optional transitionstoggle- Shows or hides elements based on visiblity, with optional transitionstransition- Apply a temporary transition to elements for animationsdispatch- Dispatch a DOM event to elements
For example, the following modal component can be shown or hidden on the client without a trip to the server:
alias Phoenix.LiveView.JS
def hide_modal(js \\ %JS{}) do
js
|> JS.hide(transition: "fade-out", to: "#modal")
|> JS.hide(transition: "fade-out-scale", to: "#modal-content")
end
def modal(assigns) do
~H"""
<div id="modal" class="phx-modal" phx-remove={hide_modal()}>
<div
id="modal-content"
class="phx-modal-content"
phx-click-away={hide_modal()}
phx-window-keydown={hide_modal()}
phx-key="escape"
>
<button class="phx-modal-close" phx-click={hide_modal()}>✖</button>
<p><%= @text %></p>
</div>
</div>
"""
endLink to this section Summary
Functions
Adds classes to elements.
Dispatches an event to the DOM.
Hides elements.
Pushes an event to the server.
Removes classes from elements.
Shows elements.
Toggles elements.
Transitions elements.
Link to this section Functions
Adds classes to elements.
names- The string of classes to add.
Options
:to- The optional DOM selector to add classes to. Defaults to the interacted element.:transition- The string of classes to apply before adding classes or a 3-tuple containing the transition class, the class to apply to start the transition, and the ending transition class, such as:{"ease-out duration-300", "opacity-0", "opacity-100"}:time- The time to apply the transition from:transition. Defaults 200
Examples
<div id="item">My Item</div>
<button phx-click={JS.add_class("highlight underline", to: "#item")}>
highlight!
</button>Dispatches an event to the DOM.
event- The string event name to dispatch.
Options
:to- The optional DOM selector to dispatch the event to. Defaults to the interacted element.:detail- The optional detail map to dispatch along with the client event. The details will be available in theevent.detailattribute for event listeners.
Examples
window.addEventListener("click", e => console.log("clicked!", e.detail))
<button phx-click={JS.dispatch("click", to: ".nav")}>Click me!</button>Hides elements.
Options
:to- The optional DOM selector to hide. Defaults to the interacted element.:transition- The string of classes to apply before hiding or a 3-tuple containing the transition class, the class to apply to start the transition, and the ending transition class, such as:{"ease-out duration-300", "opacity-0", "opacity-100"}:time- The time to apply the transition from:transition. Defaults 200
Examples
<div id="item">My Item</div>
<button phx-click={JS.hide(to: "#item")}>
hide!
</button>
<button phx-click={JS.hide(to: "#item", transition: "fade-out-scale")}>
hide fancy!
</button>Pushes an event to the server.
event- The string event name to push.
Options
:target- The selector or component ID to push to:loading- The selector to apply the phx loading classes to:page_loading- Boolean to trigger the phx:page-loading-start and phx:page-loading-stop events for this push. Defaults tofalse:value- The map of values to send to the server
Examples
<button phx-click={JS.push("clicked")}>click me!</button>
<button phx-click={JS.push("clicked", value: %{id: @id})}>click me!</button>
<button phx-click={JS.push("clicked", page_loading: true)}>click me!</button>Removes classes from elements.
names- The string of classes to remove.
Options
:to- The optional DOM selector to remove classes from. Defaults to the interacted element.:transition- The string of classes to apply before removing classes or a 3-tuple containing the transition class, the class to apply to start the transition, and the ending transition class, such as:{"ease-out duration-300", "opacity-0", "opacity-100"}:time- The time to apply the transition from:transition. Defaults 200
Examples
<div id="item">My Item</div>
<button phx-click={JS.remove_class("highlight underline", to: "#item")}>
remove highlight!
</button>Shows elements.
Options
:to- The optional DOM selector to show. Defaults to the interacted element.:transition- The string of classes to apply before showing or a 3-tuple containing the transition class, the class to apply to start the transition, and the ending transition class, such as:{"ease-out duration-300", "opacity-0", "opacity-100"}:time- The time to apply the transition from:transition. Defaults 200:display- The optional display value to set when showing. Defaults"block".
Examples
<div id="item">My Item</div>
<button phx-click={JS.show(to: "#item")}>
show!
</button>
<button phx-click={JS.show(to: "#item", transition: "fade-in-scale")}>
show fancy!
</button>Toggles elements.
Options
:to- The optional DOM selector to toggle. Defaults to the interacted element.:in- The string of classes to apply when toggling in, or a 3-tuple containing the transition class, the class to apply to start the transition, and the ending transition class, such as:{"ease-out duration-300", "opacity-0", "opacity-100"}:out- The string of classes to apply when toggling out, or a 3-tuple containing the transition class, the class to apply to start the transition, and the ending transition class, such as:{"ease-out duration-300", "opacity-100", "opacity-0"}:time- The time to apply the transition:inand:outclasses. Defaults 200:display- The optional display value to set when toggling in. Defaults"block".
Examples
<div id="item">My Item</div>
<button phx-click={JS.toggle(to: "#item")}>
toggle item!
</button>
<button phx-click={JS.show(to: "#item", in: "fade-in-scale", out: "fade-out-scale")}>
toggle fancy!
</button>Transitions elements.
transition- The string of classes to apply before removing classes or a 3-tuple containing the transition class, the class to apply to start the transition, and the ending transition class, such as:{"ease-out duration-300", "opacity-0", "opacity-100"}
Transitions are useful for temporarily adding an animation class to element(s), such as for highlighting content changes.
Options
:to- The optional DOM selector to remove classes from. Defaults to the interacted element.:time- The time to apply the transition from:transition. Defaults 200
Examples
<div id="item">My Item</div>
<button phx-click={JS.transition("shake", to: "#item")}>Shake!</button>