LiveFlow.Components.Flow (LiveFlow v0.3.2)

Copy Markdown View Source

Main Flow LiveComponent for LiveFlow.

This is the primary component that renders the entire flow diagram, including nodes, edges, background, and overlays.

Usage

<.live_component
  module={LiveFlow.Components.Flow}
  id="my-flow"
  flow={@flow}
  opts={%{minimap: true, controls: true}}
  node_types={%{custom: MyApp.CustomNode}}
/>

Attributes

  • :id - Unique ID for the component (required)
  • :flow - LiveFlow.State struct (required)
  • :opts - Configuration options map
  • :node_types - Map of node type atoms to renderers (function component or LiveComponent module)
  • :node_renderer - Fallback function component for nodes not matched by node_types
  • :on_nodes_change - Callback for node changes
  • :on_edges_change - Callback for edge changes
  • :on_connect - Callback when connection is made
  • :on_selection_change - Callback for selection changes
  • :class - Extra CSS classes for the .lf-container element

Panels

The :panel slot renders your own UI inside the flow container (React Flow's <Panel>), positioned with position (:top_left, :top_center, :top_right, :center_left, :center_right, :bottom_left, :bottom_center, :bottom_right). Panels inherit the flow theme, don't start pans or zooms, and are left out of exports. Events inside them go to the parent LiveView.

<.live_component module={LiveFlow.Components.Flow} id="flow" flow={@flow}>
  <:panel position={:top_right}>
    <button phx-click="add_node">Add node</button>
  </:panel>
</.live_component>

Options

Viewport

  • :min_zoom / :max_zoom - Zoom limits (default: 0.1 / 4.0)
  • :pan_on_drag - Pan by dragging the pane. true pans with the left and middle mouse buttons, a list selects the buttons ([0, 1, 2]), false disables it (default: true)
  • :pan_on_scroll - Scrolling pans instead of zooming (default: false)
  • :pan_on_scroll_speed - Pan speed for pan_on_scroll (default: 0.5)
  • :pan_on_scroll_mode - :free, :vertical or :horizontal (default: :free)
  • :zoom_on_scroll - Zoom with the scroll wheel (default: true)
  • :zoom_on_pinch - Zoom with trackpad pinch / ctrl+wheel (default: true)
  • :zoom_on_double_click - Zoom in on pane double click, Shift zooms out (default: true)
  • :prevent_scrolling - Keep wheel events from scrolling the page (default: true)
  • :pan_activation_key - Hold to pan with the left button from anywhere, e.g. "Space" or "Control" (default: "Space")
  • :fit_view_on_init - Fit view to content on mount (default: false)
  • :fit_view_options - %{padding: 0.1, duration: 200, min_zoom: .., max_zoom: .., nodes: [ids], include_hidden_nodes: false}

Nodes & edges

  • :nodes_draggable / :nodes_connectable / :elements_selectable (default: true)
  • :node_drag_threshold - Pixels the pointer must move before a drag starts (default: 1)
  • :node_extent - Constrain node drag/resize to {{min_x, min_y}, {max_x, max_y}} (default: nil)
  • :snap_to_grid / :snap_grid - Snap positions to a grid (default: false / {15, 15})
  • :elevate_nodes_on_select - Render selected nodes on top (default: true)
  • :elevate_edges_on_select - Render selected edges on top (default: true)
  • :z_index_mode - :basic applies the elevation options, :manual only uses each element's z_index (default: :basic)

Connections

  • :connection_mode - :strict only connects source to target handles, :loose also allows source to source (default: :strict)
  • :connection_line_type - Preview line path: :bezier, :straight, :step or :smoothstep (default: :bezier)
  • :connection_radius - Snap to the closest handle within this many pixels (default: 20)
  • :connect_on_click - Click a handle, then another one, to connect them (handy on touch devices) (default: true)
  • :multi_connection - Dragging from a selected node draws a connection line from every selected node (default: false)
  • :connection_line_style - Inline style map for the connection preview line, e.g. %{stroke: "#ff0072", "stroke-width": 3} (default: nil)
  • :connection_line_class - Extra CSS class for the connection preview line

Selection & keyboard

  • :selection_on_drag - Dragging the pane draws a selection box (default: false)
  • :selection_mode - :partial selects nodes touched by the box, :full only nodes fully inside (default: :partial)
  • :selection_key - Hold to draw a selection box (default: "Shift")
  • :multi_selection_key - Hold to add/remove elements to/from the selection (default: ["Meta", "Control", "Shift"])
  • :delete_key_code - Key(s) deleting the selection (default: ["Backspace", "Delete"])
  • :disable_keyboard_a11y - Disable moving selected nodes with the arrow keys (default: false)

Key options accept a key, a combination of any length ("Meta+Shift+s"), a list of them, or nil to disable the binding.

Opt-in events

These events are only pushed to the parent LiveView when enabled, so apps that don't handle them keep working.

  • :context_menu - Push lf:node_context_menu, lf:edge_context_menu and lf:pane_context_menu (%{"id", "x", "y", "position"}, x/y relative to the container) instead of the browser menu (default: false)
  • :pane_click_events - Push lf:pane_click (%{"position"}) when the pane is clicked without dragging (default: false)
  • :connection_events - Push lf:connect_start when a connection starts (default: false)

Always available: lf:drop (%{"data", "position"}) when an element with application/liveflow drag data is dropped on the flow, and lf:connect_cancel (%{"node_id", "handle_id", "handle_type", "position", "reason"}) when a connection is released on the pane or an invalid handle.

Auto-pan

  • :auto_pan_on_node_drag / :auto_pan_on_connect / :auto_pan_on_selection - Pan the viewport when dragging close to its edge (default: true)
  • :auto_pan_speed - Pixels per frame (default: 15)

Overlays

  • :background - Background pattern: :dots, :lines, :cross or nil
  • :background_gap - Pattern gap, number or {x, y} (default: 20)
  • :background_size - Dot radius / cross size (default: 1, cross: 6)
  • :background_offset - Pattern offset, number or {x, y} (default: 0)
  • :background_line_width - Line width for :lines and :cross (default: 1)
  • :minimap - Show minimap (default: false)
  • :minimap_pannable - Click/drag the minimap to move the viewport (default: false)
  • :minimap_zoomable - Scroll over the minimap to zoom (default: false)
  • :minimap_node_color - Color of the minimap nodes: a CSS color or a function receiving the node and returning one (React Flow's nodeColor). Minimap nodes also carry data-node-id / data-node-type for CSS.
  • :controls - Show zoom controls (default: false)
  • :theme - LiveFlow theme name (default: nil, uses default theme or inherits from app)
  • :cursors - Enable built-in remote cursor rendering for collaboration (default: false)
  • :helper_lines - Show alignment guide lines when dragging nodes (default: false)
  • :virtualization - Server-side viewport culling for large flows (default: false)

Fit view

Push a fit view from the parent LiveView with send_update/2:

send_update(LiveFlow.Components.Flow, id: "my-flow", fit_view: true)
send_update(LiveFlow.Components.Flow, id: "my-flow", fit_view: %{nodes: ["a", "b"], padding: 0.2})

Bounds are computed on the server (LiveFlow.State.bounds/2), so nodes culled by virtualization are included.