Manages a dynamic list of items with add/remove/reorder reconciliation. Each item is identified by a unique key. When the list changes, only the changed items are updated. component.each differs from component.each_live in that it does a full re-render of the HTML element instead of patches.

Avoid using each for list items that contain <input>, <textarea>, or <select> elements, each changed item replaces its DOM via innerHTML, destroying focus and in-progress user input. Use each_live with targeted patches instead.

slice must return a List rather than a single element, unlike component.simple.

While the type for key can be defined by the user, internally, these are converted to String.

The render function is called for each item and returns a Component. For plain HTML items, wrap with component.static.

Event bindings declared inside render are not collected. Attach per-list events to this each component or any ancestor (selectors are global, so one handler on .card covers every card).

component.each(
  slice: fn(model) { model.counters },
  key: fn(counter) { counter.id },
  render: fn(counter) {
    component.static(fn(_) {
      html.div([class("counter")], [
        html.text(int.to_string(counter.value))
      ])
    })
  }
)

Manages a dynamic list of items with add/remove/reorder reconciliation. Each item is identified by a unique key. When the list changes, only the changed items are updated. component.each_live differs from component.each in that patches to the DOM element are applied instead of a full re-render. This is useful when list items are updated frequently.

slice must return a List rather than a single element, unlike component.live.

While the type for key can be defined by the user, internally, these are converted to String.

The initial function returns a Component for each item’s first render. Wrap plain HTML with component.static. The patch function returns patches applied on updates (the item’s root must remain).

Event bindings declared inside initial are not collected. Attach per-list events to this each_live component or any ancestor (selectors are global, so one handler covers every item).

component.each_live(
  slice: fn(model) { model.series },
  key: fn(series) { series.id },
  initial: fn(series) {
    component.static(fn(_) {
      html.div([class("display-data")], [
        html.span([class("value")], [html.text("0")])
      ])
    })
  },
  patch: fn(series) {
    [SetText(".value", int.to_string(series.value))]
  },
)

Fragments allow you to return multiple components from a single function. The children are rendered in order and concatenated into the parent’s HTML. Similar to Lustre’s element.fragment.

fn app(_model: Model) -> Component(Model, Message, Element(Message)) {
  component.fragment([
    component.static(fn(_) { html.h1([], [html.text("My App")]) }),
    component.simple(...),
    component.each(...),
  ])
}

Live components render an initial HTML structure once, then apply DOM patches on subsequent updates. This avoids the full innerHTML replacement of simple, which means existing nodes are never destroyed between updates.

Use live whenever the component contains <input>, <textarea>, or <select> elements. Because the DOM nodes are preserved, focus, cursor position, and any in-progress user input survive model updates. This also makes live the right choice for high-frequency updates such as drag-and-drop, animations, and real-time data (60fps rendering).

The patch function returns a list of Patch values. Each patch targets an element relative to the component’s root using a CSS selector.

The first parameter of initial is a Slotter, call slot(child_component) wherever you want a nested component to appear. Ignore it with _ if no children are needed.

Example

component.live(
  slice: fn(model) { model.data },
  initial: fn(_) {
    html.div([], [
      html.span([class("value")], [html.text("0")]),
      html.div([class("bar")], [])
    ])
  },
  patch: fn(data) {
    [
      SetText(".value", int.to_string(data)),
      SetStyle(".bar", "width", int.to_string(data) <> "%"),
    ]
  }
)

This is the entry point for rendering, mounting a component tree to a specific DOM element. It creates a subscription to the store, renders the entire component tree, and walks the tree to register every event binding attached via event.on() and friends.

• selector: CSS selector for the mount point (e.g., "#app")
• to_html: Function to convert html type to String (e.g., element.to_string for Lustre or fn(html) {html} for raw HTML strings)
• to_slot: Zero-argument function returning an html placeholder value that serialises to <lily-slot></lily-slot>. Used when nesting components via Slotter. For Lustre: fn() { element.element("lily-slot", [], []) }. For raw HTML strings: fn() { "<lily-slot></lily-slot>" }.
• view: Function that takes the model and returns the root component tree

mount can be called more than once on a shared runtime, with different selectors, to drive multiple DOM roots from one model. This is how overlays / portals work: mount your main view at #app and a secondary overlays view at #overlays. Both views subscribe to the same model and update on every dispatch. Calling mount twice on the same selector tears down the previous mount and replaces it.

runtime
|> component.mount(
  selector: "#app",
  to_html: element.to_string,
  to_slot: fn() { element.element("lily-slot", [], []) },
  view: app,
)

Render a view to an HTML string without touching the DOM. Walks the Component tree, calling each render / initial / content function and piping through to_html. Compiles on both targets, so it can produce the initial page markup ahead of time (at build time, or from a plain request handler) rather than on a live DOM. Pair with transport.encode_initial_snapshot to embed the matching initial state and client.hydrate so the client adopts the pre-rendered DOM instead of re-rendering it on load. This is static pre-rendering plus hydration from a fixed snapshot, not per-request server-side rendering.

Nested components placed via the Slotter callback are rendered inline: the walker renders each child to a string and uses from_string to wrap that string back as an html value the user composes into the parent. For raw-HTML libraries where html is just String, from_string is the identity. For Lustre, pass an unsafe_raw_html-style constructor that inserts the string verbatim.

Event bindings, focus management, and CSS transitions are skipped: they only make sense on a live DOM. For live and each_live, the initial baseline is rendered; patches only apply at runtime via mount.

let html = component.render_to_string(
  view: shared.view,
  model: shared.initial_model(),
  to_html: element.to_string,
  from_string: element.unsafe_raw_html(_, "div", [], _),
)

When you want to disable a component when the transport is disconnected, this allows you to do that. The connected function extracts the connection status from the model. When it returns False, Lily adds data-lily-disabled="true" and aria-disabled="true" attributes plus a lily-disconnected CSS class to the component’s root element, and prevents all event handlers from firing. Custom styling, such as greying the component out or changing opacity, can be achieved with simple CSS styling.

Pipe this after creating a component.

component.simple(
  slice: fn(model) { model.transfer_amount },
  render: fn(amount, _) {
    html.button([], [html.text("Transfer $" <> int.to_string(amount))])
  },
)
|> component.require_connection(fn(model) { model.connected })

This is the most common component type. It subscribes to a slice of the model and re-renders the entire component when that slice changes.

The render function receives the slice value and a Slotter. Call slot(child_component) wherever you want a nested component to appear, or ignore the slot parameter with _ if no children are needed.

Avoid using simple for components that contain <input>, <textarea>, or <select> elements, every slice change replaces the component’s entire DOM via innerHTML, which destroys focus and any in-progress user input. Use live with targeted patches instead.

component.simple(
  slice: fn(model) { model.count },
  render: fn(count, _) {
    html.div([], [html.text("Count: " <> int.to_string(count))])
  }
)

Pipe through event.on() and friends to attach DOM event handlers to the rendered subtree, registered once at mount.

Static components render once and never update. Useful for headers, static text, or any content that doesn’t depend on the model.

The content function receives a Slotter. Call slot(child_component) wherever you want a nested component to appear, or ignore the slot parameter with _ if no children are needed.

component.static(fn(_) { html.h1([], [html.text("My App")]) })

Switch a component’s comparison strategy from reference to structural equality. By default, components use reference equality (===) to detect slice changes. This works well for primitives and unchanged references.

Use structural() when your slice function returns new tuples, lists, or other constructed values on every call.

Static and Fragment components don’t compare slices, so this returns them unchanged; decorations are left untouched.

component.simple(
  slice: fn(model) { #(model.x, model.y) },  // Returns new tuple each time
  render: fn(pos, _) { ... }
)
|> component.structural  // Enable deep equality check

Single-slot dynamic switching with identity preservation. slice picks a discriminator from the model; build turns that discriminator into a Component. When the slice value is unchanged across renders, the wrapper and child DOM are not touched, so focus, selection, and in-progress input survive. When the slice changes, the old child’s handlers are unregistered, the new Component is built and rendered, and the wrapper’s innerHTML is replaced.

Switch compares by reference equality by default, pipe through structural when the slice constructs new values on every call (tuples, records). Pair with event.on() on the Switch itself to bind events: bindings declared inside build’s returned Component are not collected at mount and never fire. Selectors are global, so one handler on .panel-close covers every panel rendered by the switch.

Example

component.switch(
  on: fn(model: Model) { model.route },
  case_of: fn(route) {
    case route {
      Home -> home_page()
      Profile -> profile_page()
      Settings -> settings_page()
    }
  },
)

Decorate a component with enter and exit CSS classes timed to a duration. Pipe-friendly: the component comes first, so it chains like the other decorators (event.on*, require_connection). On mount, the wrapper carries enter for duration_milliseconds, then the class is removed. On unmount (when an enclosing each, each_live, or switch removes the wrapper), exit is applied and DOM removal is deferred by the same duration, with animationend taking precedence if the CSS fires it first.

The CSS contract is keyframes-based:

.dialog-enter { animation: dialog-enter 200ms; }
.dialog-exit  { animation: dialog-exit 200ms forwards; }
@keyframes dialog-enter { from { opacity: 0 } to { opacity: 1 } }
@keyframes dialog-exit  { from { opacity: 1 } to { opacity: 0 } }

forwards on exit keeps the final state visible while the framework holds the element in the DOM, preventing a flicker before removal.

Placement rule: transitions fire only when the framework’s removal path runs through them. That happens for each, each_live, and switch child removal. Placing a transition inside a simple’s render does not run exits on parent re-render, since simple’s innerHTML wipe is synchronous. Hoist the transition to an each_live item or a switch child if you need exits to fire.

Example

component.each_live(
  slice: fn(model) { model.toasts },
  key: fn(toast) { int.to_string(toast.id) },
  initial: fn(toast) {
    component.static(fn(_) { render_toast(toast) })
    |> component.transition(
      enter: "toast-enter",
      exit: "toast-exit",
      duration_milliseconds: 200,
    )
  },
  patch: fn(_) { [] },
)