Laminar Documentation

Laminar provides several resources for developers:

• Official Website (laminar.dev): Contains the sales pitch, quick start guides, full documentation, and live examples.
• Live Demo (demo.laminar.dev): A fully working client + server setup including dev and prod build configurations. You can use this to experiment with code snippets and see how to deploy to the cloud.

Laminar can natively render various types if appropriate implicit instances are available:

• Primitives: Int, Boolean, Double, and Long can be rendered directly via text <-- observableOfInt without calling .toString.
• Custom Components: Any type Component with an implicit RenderableNode[Component] can be used with child <-- or children <--.
• Custom Text: Any type A with an implicit RenderableText[A] can be used with text <--.

In Laminar, elements are created by calling an HTML tag function (e.g., div(), input()) and passing Modifier objects to it. A Modifier[El] (aliased as Mod[El]) is a function that modifies an element.

To set an attribute or property, use the := operator with an HtmlAttr or HtmlProp.

Example:

input(typ := "checkbox", defaultChecked := true)

Alternatively, you can use the shorthand syntax where the attribute name is called as a method:

input(typ("checkbox"), defaultChecked(true))

Note: typ and other keys come from Scala DOM Types. You should consult their documentation for naming differences compared to the native JS DOM API.

When integrating third-party libraries that require explicit initialization and cleanup (like D3, ZIO, or the DOM), use CustomSource. This provides onStart and onStop hooks, which are more robust than using an EventBus for lifecycle-managed resources.

To implement a custom source, use CustomStreamSource and provide a CustomSource.Config containing onStart and onStop logic.

// Conceptual implementation of a custom source
CustomStreamSource[Ev]( (fireValue, fireError, getStartIndex, getIsStarted) => {
  val eventHandler: js.Function1[Ev, Unit] = fireValue

  CustomSource.Config(
    onStart = () => {
      eventTarget.addEventListener(eventKey, eventHandler, useCapture)
    },
    onStop = () => {
      eventTarget.removeEventListener(eventKey, eventHandler, useCapture)
    }
  )
})

The --> (Observer) and <-- (Observable) methods are the primary syntax for connecting data streams to elements. These methods return a Modifier that handles the lifecycle of the subscription:

1. Activation: The subscription starts when the element is mounted to the DOM.
2. Deactivation: The subscription automatically stops when the element is unmounted.

Modifiers are categorized into two types:

• Binder: Handles properties, attributes, or events (e.g., onClick.map(...) --> observer).
• Inserter: Handles adding children to an element (e.g., children <-- observable).

Laminar elements are not Virtual DOM nodes; they are one-to-one linked to actual JS DOM elements (accessible via the .ref property).

Because there is no Virtual DOM diffing, you must define dynamic behavior inside the element using reactive operators. This allows for precision DOM updates. For example, to make a text node or a CSS property dynamic, you use the <-- operator to bind a stream to that specific property or child.

// Static property
fontSize := "20px", 

// Dynamic property via stream
color <-- helloColorStream, 

// Dynamic child (text node)
text <-- streamOfNames

Airstream 15.0.0 introduces a new paradigm: instead of tearing down state when an observable is stopped, it now pauses and resumes.

• Old Behavior: Stopping an observable often reset its internal state. For example, a combineWith stream would "forget" previous values and require both parents to emit again before producing a new combined value.
• New Behavior: Observables generally remember their last known state. When restarted, they resume from that state, allowing for a more seamless experience when components are unmounted and remounted.

An EventBus[A] is a specialized structure that acts as both a source and a sink for events. It contains a .writer (an Observer) and .events (an EventStream). This design allows you to share read-only or write-only parts of the bus easily.

To use an EventBus:

1. Create a new EventBus[T].
2. Use element.eventProp --> eventBus.writer to feed events into the bus.
3. Use eventBus.events.map(...) to derive new streams from the bus.
4. Use stream --> observer to consume the processed events.

val clickBus = new EventBus[dom.MouseEvent]
val coordinateStream: EventStream[Int] = clickBus.events.map(ev => ev.screenX)
val coordinateObserver = Observer[Int](onNext = x => dom.console.log(x))
 
val element: Div = div(
  onClick --> clickBus.writer,
  "Click me",
  coordinateStream --> coordinateObserver
)