Live View

How It Works

Live View is a server-rendered component system that maintains state on the server. When users interact with the page, events are sent over WebSockets, the server updates the component state, re-renders the template, and sends back a compact patch with just the changed lines. The client then morphs the live region's DOM to match — nodes are updated in place, not replaced (see How Patches Reach the DOM).

Creating a Live View Component

Step 1: Create the Template

Create a template in app/views/live/ (.html.slv; .slv, .sliv, and .html.erb also resolve). State is interpolated with standard ERB tags.

<div class="counter-component">
  <h2>Count: <%= count %></h2>

  <button soli-click="decrement">-</button>
  <button soli-click="increment">+</button>
</div>

Step 2: Register the Route

Register your Live View component in config/routes.sl using the router_live function.

# Register LiveView components
router_live("counter", "live#counter");
router_live("metrics", "live#metrics");

Step 3: Create the Controller

Create a controller that handles events. The handler receives an event hash with event (name), params, and state. Return the new state as a hash.

# Counter component handler
def counter(event_data: Any) -> Any {
  event = event_data["event"]   # Event name (e.g., "increment")
  state = event_data["state"]   # Current component state
  count = state["count"] || 0

  if event == "increment"
    { "count": count + 1 }
  elsif event == "decrement"
    { "count": count - 1 }
  else
    state                       # Unchanged for unknown events
  end
}

Available Directives

Two more attributes control how the DOM morph treats an element (they trigger nothing on the server):

State Management

State is stored on the server, and each state key is available in the template as a plain ERB variable. The server maintains state between events.

<!-- Simple variable -->
<span>Hello, <%= username %></span>

<!-- Conditional rendering -->
<% if logged_in %>
  <a href="/logout">Sign Out</a>
<% else %>
  <a href="/login">Sign In</a>
<% end %>

<!-- Iteration -->
<% for item in items %>
  <li><%= item["name"] %></li>
<% end %>

Client Setup

The client is served by the soli binary itself at /live/client.js — no file to vendor, always in sync with the server's patch protocol. Include it only on pages that mount a live component — it is ~7 KB gzipped (~30 KB raw) and auto-connects every [data-liveview-url] element on DOMContentLoaded.

<!-- Include the Live View client (built into the binary, ~7 KB gzipped) -->
<script src="/live/client.js"></script>

<!-- Mount a Live View component (auto-connects on page load) -->
<div data-live-root data-liveview-url="/live/socket/counter"></div>

To control connection timing yourself (e.g. after a client-side navigation that doesn't re-fire DOMContentLoaded), add data-liveview-manual to skip auto-connect and call live() by hand:

<div data-live-root data-liveview-manual data-liveview-url="/live/socket/counter"></div>

<script>
  window.live("wss://example.com/live/socket/counter", { rootElement: document.querySelector("[data-live-root]") });
</script>

How Patches Reach the DOM

When state changes, the server re-renders the template, diffs the result against the previous render, and ships just the changed lines over the socket. The client keeps a shadow copy of the exact HTML it last received, applies the patch to it, then morphs the live region's real DOM to match:

If the client ever fails to apply a patch (lost shadow, version skew), it asks the server to replay the last full render — recovery is automatic and keeps server-side state intact.

Route Configuration

Register the Live View WebSocket endpoint in your routes.

# Live View component endpoint
router_live("counter", "live#counter");

Lifecycle Events

Two synthetic events are dispatched by the server in addition to user-driven directives:

• connect — fired once, immediately after the WebSocket is established and before any client events. Use it to seed initial state and (optionally) start a tick timer.
• tick — fired on a recurring interval requested by the handler (see below). Use it for server-pushed updates like dashboards or live charts.

High-Rate Updates with Ticks

For real-time dashboards, monitoring, and live data feeds, a handler can opt into a per-instance recurring tick. Return the wrapped form { "state": {...}, "tick_interval": <ms> } from any handler invocation — typically from connect — and the server will fire tick events on that interval.

def metrics_dashboard(event_data: Any) -> Any {
  event = event_data["event"]

  if event == "connect"
    # Set tick interval in milliseconds (50ms = 20 updates/sec)
    {
      "state": { "cpu": 0, "memory": 0, "requests": 0 },
      "tick_interval": 50
    }
  elsif event == "tick"
    # Server pushes fresh data on each tick
    {
      "state": {
        "time": datetime_now(),
        "cpu": system_cpu_usage(),
        "memory": system_memory_mb(),
        "requests": request_counter
      }
    }
  else
    # Unknown event — leave state and tick interval unchanged
    event_data["state"]
  end
}

<div class="dashboard">
  <div class="metric">
    <span class="label">Server Time</span>
    <span class="value"><%= time %></span>
  </div>
  <div class="metric">
    <span class="label">CPU</span>
    <span class="value"><%= cpu %>%</span>
  </div>
  <div class="metric">
    <span class="label">Memory</span>
    <span class="value"><%= memory %> MB</span>
  </div>
  <div class="metric">
    <span class="label">Requests/sec</span>
    <span class="value"><%= requests %></span>
  </div>
</div>

Live Demo: Server Clock

This is a tick-driven component running live against this site's live#metrics handler. The server fires a tick event every 50ms, recomputes the time, and pushes back a patch.

tick_interval Semantics

The handler may return either shape on any invocation:

• Bare: { ...state } — the whole hash is the new state. Equivalent to tick_interval absent.
• Wrapped: { "state": {...}, "tick_interval": N } — state is the new state; tick_interval controls the timer.

If a tick fires while the previous handler call is still running, the tick is dropped (rather than queued) so a slow handler doesn't snowball. Ticks stop automatically when the WebSocket closes.

Reactive Live Queries

A tick polls on a timer; a live query pushes only when the data changes. Call Model.live_where(filter) inside a handler instead of where(filter).all(): it runs the same query and subscribes this LiveView to the collection. When any request later writes to that collection, the framework re-runs the handler and pushes a patch — no polling, no manual pub/sub.

# app/controllers/live_controller.sl
def posts_board(event_data: Any) -> Any {
  # Re-queries on connect and on every change to the collection. The render is
  # diffed server-side, so an unrelated write yields an empty diff and no frame.
  { "posts": Post.live_where({ "published": true }) }
}

Nothing else is required: writing a Post from an ordinary controller (Post.create(...), post.save(), post.destroy()) wakes every board viewing it. live_where returns the same instances as where(...).all(), so a template that iterated the old result needs no changes. Outside a LiveView render it is where(...).all() — the subscription is a no-op — so it's a safe drop-in.

Streams

A full re-render diffs the whole component; for an append-only or large list (a chat log, feed, leaderboard) that re-diffs every old row on each new one. A stream instead sends targeted DOM ops that the client applies directly to a container — no list re-render. Render the container empty (its items stay out of the diff, so patches never fight the streamed nodes), give it a stable id, and return a stream sub-hash from the handler:

def feed(event_data) {
  if event_data["event"] == "new_message" {
    msg = event_data["params"]
    return {
      "stream": {
        "container": "messages",
        "ops": [
          { "op": "append", "id": "msg-#{msg["id"]}", "html": "<li id=\"msg-#{msg["id"]}\">#{h(msg["text"])}</li>" }
        ]
      }
    }
  }
  { "count": 0 }   # connect: initial state
}

The returned hash may carry state and stream together, or stream alone (state untouched). Ops: append/prepend (id, html), insert (id, html, before?), remove (id), reset. container is hoisted on the stream hash and applies to every op. Rows should carry a stable id so re-adds de-dupe and remove can find them. Streamed nodes live outside the diff shadow, so a reconnect re-mounts from the empty render — re-drive the stream on connect if the list must survive one.

Performance

Current Limitations

Live View is young. Server-pushed re-renders and DOM-aware patching work well; some edges remain: