Events & JavaScript API

LiveFlow splits the work between the browser and the server: the LiveFlow hook handles every interaction on the client and reports the results to your LiveView as lf:* events; your LiveView updates the LiveFlow.State and re-renders. This guide lists every event in both directions, the DOM events you can dispatch from HEEx, and the JavaScript API exposed on the flow element.

How Events Reach Your LiveView

The hook calls pushEvent, so events go to the LiveView that renders the Flow component (not to the component itself). Handle the ones you need and keep a catch-all for the rest:

alias LiveFlow.Changes.{EdgeChange, NodeChange}

def handle_event("lf:node_change", %{"changes" => changes}, socket) do
  {:noreply, assign(socket, flow: NodeChange.apply_changes(socket.assigns.flow, changes))}
end

def handle_event("lf:edge_change", %{"changes" => changes}, socket) do
  {:noreply, assign(socket, flow: EdgeChange.apply_changes(socket.assigns.flow, changes))}
end

# Events you don't use (lf:drag_move, lf:cursor_move, ...)
def handle_event("lf:" <> _event, _params, socket), do: {:noreply, socket}

# Node clicks arrive as a message
def handle_info({:lf_node_click, _node_id}, socket), do: {:noreply, socket}

Getting Started shows a complete set of handlers. All payload keys are strings, positions are in flow coordinates (%{"x" => x, "y" => y}) unless noted otherwise.

Events Sent to Your LiveView

Nodes

Change maps in lf:node_change:

LiveFlow.Changes.NodeChange.apply_changes/2 handles all of them.

Edges

LiveFlow.State.reconnect_edge/3 accepts the lf:reconnect_edge params as they come.

Connections

lf:connect_end is a request: nothing is added until you add the edge, usually after validating it with LiveFlow.Validation.Connection.validate_and_create/3. See Interaction.

Selection, Deletion and Viewport

Keyboard Commands

The hook only sends these; the behavior is yours to implement (for example with LiveFlow.History and LiveFlow.Clipboard, see Interaction).

Keys typed in inputs, textareas and content-editable elements are ignored, and with several flows on a page only the focused (or last used) flow reacts.

Pane, Drag & Drop and Context Menus

In the context menu events "x"/"y" are pixels relative to the flow container (to position a menu inside it) and "position" is in flow coordinates.

Layout and Collaboration

lf:container_resize is sent to the Flow component itself (minimap and virtualization) and never reaches your LiveView.

Events You Push to the Client

Send these with Phoenix.LiveView.push_event/3. Events marked with flow_id accept an optional flow_id (the Flow component id): with several flows on the page, only that one reacts.

Prefer the Elixir helpers where they exist:

# Fit the view, computing the bounds on the server (works with virtualization)
send_update(LiveFlow.Components.Flow, id: "my-flow", fit_view: %{nodes: ["a", "b"], padding: 0.2})

# Animate to a server-side layout
positions = LiveFlow.Layout.tree(flow, direction: :lr)
socket = LiveFlow.animate_positions(socket, "my-flow", flow, positions, fit_view: true)

LiveFlow.Collaboration pushes lf:remote_cursor, lf:cursor_leave and lf:remote_drag for you; see Collaboration.

DOM Events

Some actions must run in the browser (they read the current client viewport or start a download, which needs the user's click). Dispatch them on the flow element with Phoenix.LiveView.JS.dispatch/2:

<button phx-click={JS.dispatch("lf:fit-view", to: "#my-flow", detail: %{padding: 0.2})}>
  Fit view
</button>
<button phx-click={JS.dispatch("lf:export-png", to: "#my-flow", detail: %{scale: 2})}>
  Download PNG
</button>

JavaScript API

When the hook mounts, the flow element gets a liveflow property (the equivalent of React Flow's useReactFlow()), and the element dispatches an lf:ready event whose detail is the same object. lf:ready doesn't bubble: listen on the flow element.

The API reads the browser state, so it only sees rendered nodes (with virtualization: true, nodes outside the viewport are not rendered). Use it from a hook, for example to turn a pointer position into flow coordinates:

<div id="stamp" phx-hook=".Stamp" data-flow="#my-flow">Click the flow</div>
<script :type={Phoenix.LiveView.ColocatedHook} name=".Stamp">
  export default {
    mounted() {
      const flow = document.querySelector(this.el.dataset.flow)
      flow.addEventListener("dblclick", (event) => {
        const position = flow.liveflow.screenToFlowPosition({x: event.clientX, y: event.clientY})
        this.pushEvent("add_note", {position})
      })
    }
  }
</script>

If the hook may mount after yours, wait for lf:ready:

const flow = document.getElementById("my-flow")
if (flow.liveflow) init(flow.liveflow)
else flow.addEventListener("lf:ready", (event) => init(event.detail), {once: true})

JavaScript Exports

Besides the hook, the live_flow package exports: