A keyed dynamic list, reconciled by add/remove/reorder so only changed items update. Like each_live but each changed item is re-rendered via innerHTML rather than patched.

Avoid each for items containing <input>, <textarea>, or <select>, the innerHTML replace destroys focus and in-progress input. Use each_live there.

slice returns a List, and render returns a Component per item (wrap plain HTML with static). Keys can be any type, they are stringified internally. Event bindings inside render aren’t collected, so put per-list events on this component or any ancestor.

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))
      ])
    })
  }
)

A keyed dynamic list, reconciled by add/remove/reorder so only changed items update. Like each but items are patched instead of re-rendered, which suits frequently-updated items.

slice returns a List. initial returns the first-render Component per item (wrap plain HTML with static), and patch returns the patches for updates (the item’s root must survive). Keys can be any type, they are stringified internally. Event bindings inside initial aren’t collected, so put per-list events on this component or any ancestor.

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))]
  },
)

Returns several components from one function. Children render in order and concatenate into the parent’s HTML, like 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(...),
  ])
}

Renders an initial HTML structure once, then applies targeted DOM patches on update instead of the full innerHTML replace of simple, so existing nodes survive between updates.

Reach for live whenever the component holds <input>, <textarea>, or <select>, since preserving nodes keeps focus, cursor, and in-progress input intact. It also suits high-frequency updates like drag-and-drop, animation, and real-time data.

patch returns Patch values, each targeting an element under the component root by CSS selector. initial’s first parameter is a Slotter, call slot(child) where a nested component should go, or ignore it with _.

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) <> "%"),
    ]
  }
)

The entry point for rendering. Mounts a component tree onto a DOM element, subscribes it to the store, and registers every event binding attached via event.on() and friends.

• selector: the mount point, e.g. "#app"
• to_html: converts your html type to a String, element.to_string for Lustre or fn(html) { html } for raw strings
• to_slot: returns an html placeholder that serialises to <lily-slot></lily-slot>, used when nesting via Slotter
• view: takes the model and returns the root component tree

Call mount more than once on a shared runtime, with different selectors, to drive several DOM roots from one model. This is how overlays and portals work. Mounting the same selector again replaces the previous mount.

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, walking the Component tree and piping each render through to_html. It compiles on both targets, so you can produce the initial markup ahead of time, at build time or from a plain request handler. Pair it with transport.encode_initial_snapshot and client.hydrate so the client adopts the pre-rendered DOM instead of re-rendering. This is static pre-rendering plus hydration, not per-request server-side rendering.

Nested components placed via the Slotter callback render inline, from_string wraps each child’s string back into an html value. For raw-HTML libraries it’s the identity, for Lustre pass an unsafe_raw_html-style constructor.

Event bindings, focus, and CSS transitions are skipped since they only make sense on a live DOM. For live and each_live the initial baseline renders, patches apply only 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", [], _),
)

Disables a component while the transport is disconnected. connected reads the connection status from the model, and when it returns False Lily adds data-lily-disabled="true", aria-disabled="true", and a lily-disconnected class to the root and stops event handlers firing. Style the disconnected state however you like with CSS. Pipe it on after building 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 })

Record a component’s own CSS selector (usually #<id>) as its scope, so the scoped event.on* binders match only within its subtree. Pipe it on after giving the component an id, then pipe on event.on without a selector. Component-library builders scope their widget from the id they already render.

Example

component.simple(slice: ..., render: ...)
|> component.scoped("#search")
|> event.on(event: event.input, handler: Search)

The most common component type. It subscribes to a slice of the model and re-renders the whole component through innerHTML when that slice changes.

render receives the slice value and a Slotter, call slot(child) where a nested component should go, or ignore it with _.

Avoid simple for components holding <input>, <textarea>, or <select>, the innerHTML replace destroys focus and in-progress input. Use live there.

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.

Renders once and never updates. Good for headers, static text, or anything that doesn’t depend on the model.

content receives a Slotter, call slot(child) where a nested component should go, or ignore it with _.

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

Switch a component’s comparison from reference to structural equality. By default components use reference equality (===), which suits primitives and unchanged references. Reach for structural() when your slice returns new tuples, lists, or other constructed values each call.

Static and Fragment don’t compare slices, so this returns them unchanged.

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 that preserves identity. on picks a discriminator from the model and case_of turns it into a Component. While the discriminator is unchanged the wrapper and child DOM are left alone, so focus, selection, and input survive. When it changes, the old child’s handlers are unregistered and the new Component replaces the wrapper’s innerHTML.

Compares by reference by default, pipe through structural when the slice builds new values each call. Bind events with event.on() on the switch itself, bindings inside the built Component aren’t collected and never fire.

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. The component comes first so it chains like the other decorators. On mount the wrapper carries enter for duration_milliseconds, then drops it. On unmount (when an enclosing each, each_live, or switch removes it) exit is applied and DOM removal is deferred by the same duration, with animationend winning 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, which is each, each_live, and switch child removal. A transition inside a simple render won’t run exits on parent re-render, since that innerHTML wipe is synchronous. Hoist it to an each_live item or switch child if you need exits.

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(_) { [] },
)