phx- HTML attributes

View Source

A summary of special HTML attributes used in Phoenix LiveView templates. Each attribute is linked to its documentation for more details.

Event Handlers

Attribute values can be:

Use phx-value-* attributes to pass params to the server.

Use phx-debounce and phx-throttle to control the frequency of events.

Click

Attributes
phx-click phx-click-away

Focus

Attributes
phx-blur phx-focus
phx-window-blur phx-window-focus

Keyboard

Attributes
phx-keydown phx-keyup
phx-window-keydown phx-window-keyup

Use the phx-key attribute to listen to specific keys.

Scroll

Attributes
phx-viewport-top phx-viewport-bottom

Example

lib/hello_web/live/hello_live.html.heex

<button type="button" phx-click="click" phx-value-user={@current_user.id}>Click Me</button>
<button type="button" phx-click={JS.toggle(to: "#example")}>Toggle</button>

Form Event Handlers

On <form> elements

AttributeValue
phx-changeEvent name or JS commands
phx-submitEvent name or JS commands
phx-auto-recoverEvent name, JS commands or "ignore"
phx-trigger-actiontrue or false

On <button> elements

AttributeValue
phx-disable-withText to show during event submission

Form Example

lib/hello_web/live/hello_live.html.heex

<form phx-change="validate" phx-submit="save">
  <input type="text" name="name" phx-debounce="500" phx-throttle="500" />
  <button type="submit" phx-disable-with="Saving...">Save</button>
</form>

Socket Connection Lifecycle

AttributeValue
phx-connectedJS commands executed after the LiveSocket connects
phx-disconnectedJS commands executed after the LiveSocket disconnects

lib/hello_web/live/hello_live.html.heex

<div id="status" class="hidden" phx-disconnected={JS.show()} phx-connected={JS.hide()}>
  Attempting to reconnect...
</div>

DOM Element Lifecycle

AttributeValue
phx-mountedJS commands executed after the element is mounted
phx-removeJS commands executed during the element removal
phx-update"replace" (default), "stream" or "ignore", configures DOM patching behavior

lib/hello_web/live/hello_live.html.heex

<div
  id="iframe-container"
  phx-mounted={JS.transition("animate-bounce", time: 2000)}
  phx-remove={JS.hide(transition: {"transition-all transform ease-in duration-200", "opacity-100", "opacity-0"})}
>
  <button type="button" phx-click={JS.exec("phx-remove", to: "#iframe-container")}>Hide</button>
  <iframe id="iframe" src="https://example.com" phx-update="ignore"></iframe>
</div>

Client Hooks

AttributeValue
phx-hookThe name of a previously defined JavaScript hook in the LiveSocket

Client hooks provide bidirectional communication between client and server using this.pushEvent and this.handleEvent to send and receive events.

lib/hello_web/live/hello_live.html.heex

<div id="example" phx-hook="Example">
  <h1>Events</h1>
  <ul id="example-events"></ul>
</div>

assets/js/app.js

let Hooks = {}
Hooks.Example = {
  // Callbacks
  mounted()      { this.appendEvent("Mounted") },
  beforeUpdate() { this.appendEvent("Before Update") },
  updated()      { this.appendEvent("Updated") },
  destroyed()    { this.appendEvent("Destroyed") },
  disconnected() { this.appendEvent("Disconnected") },
  reconnected()  { this.appendEvent("Reconnected") },

  // Custom Helper
  appendEvent(name) {
    console.log(name)
    let li = document.createElement("li")
    li.innerText = name
    this.el.querySelector("#example-events").appendChild(li)
  }
}

let liveSocket = new LiveSocket("/live", Socket, {hooks: Hooks})

Tracking Static Assets

AttributeValue
phx-track-staticNone, used to annotate static files

lib/hello_web/components/layouts/root.html.heex

<link phx-track-static rel="stylesheet" href={~p"/assets/app.css"} />
<script defer phx-track-static type="text/javascript" src={~p"/assets/app.js"}></script>