Phoenix.LiveView.JS (Phoenix LiveView v0.17.0) 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 classing, 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:

<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 transitions
remove_class - Remove classes from elements, with optional transitions
show - Show elements, with optional transitions
hide - Hide elements, with optional transitions
toggle - Shows or hides elements based on visiblity, with optional transitions
transition - Apply a temporary transition to elements for animations
dispatch - 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:

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>
  """
end

Link to this section Summary

Functions

add_class(names)

Adds classes to elements.

add_class(js, names)

add_class(js, names, opts)

dispatch(cmd \\ %JS{}, event, opts)

Dispatches an event to the DOM.

hide(cmd \\ %JS{}, opts)

Hides elements.

push(event)

Pushes an event to the server.

push(event, opts)

push(cmd, event, opts)

remove_class(names)

Removes classes from elements.

remove_class(js, names)

remove_class(js, names, opts)

show(cmd \\ %JS{}, opts)

Shows elements.

toggle(cmd \\ %JS{}, opts)

Toggles elements.

transition(names)

Transitions elements.

transition(names, opts)

transition(cmd, names, opts)

Link to this section Functions

add_class(names)

Adds classes to elements.

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.
: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>

add_class(js, names)

add_class(js, names, opts)

dispatch(cmd \\ %JS{}, event, opts)

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 the event.detail attribute for event listeners.

Examples

window.addEventListener("click", e => console.log("clicked!", e.detail))

<button phx-click={JS.dispatch("click", to: ".nav")}>Click me!</button>

hide(cmd \\ %JS{}, opts)

Hides elements.

Options

:to - The optional DOM selector to hide. defaults to the interacted element.
:transition - The string of classes to apply before hiding.
: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>

push(event)

Pushes an event to the server.

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. Default false
: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>

push(event, opts)

push(cmd, event, opts)

remove_class(names)

Removes classes from elements.

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.
: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>

remove_class(js, names)

remove_class(js, names, opts)

show(cmd \\ %JS{}, opts)

Shows elements.

Options

:to - The optional DOM selector to show. defaults to the interacted element.
:transition - The string of classes to apply before showing.
: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>

toggle(cmd \\ %JS{}, opts)

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.
:out - The string of classes to apply when toggling out.
:time - The time to apply the transition :in and :out classes. 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>

transition(names)

Transitions elements.

Transitions are useful for temporarily adding an animation class to element(s), such as for highligthing content changes.

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.
: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>

transition(names, opts)

transition(cmd, names, opts)