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

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

Link to this section Summary

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>
Link to this function

add_class(js, names, opts)

View Source
Link to this function

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

View Source

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>

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 to 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>

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>
Link to this function

remove_class(js, names, opts)

View Source

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

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>
Link to this function

transition(transition, opts)

View Source
Link to this function

transition(cmd, transition, opts)

View Source