Schedule a side effect that is guaranteed to run after the browser has painted the screen.

In addition to the dispatch function, your callback will also be provided with root element of your app or component. This is especially useful inside of components, giving you a reference to the Shadow Root.

Note: There is no concept of a “paint” for server components. These effects will be ignored in those contexts and never run.

Batch multiple effects to be performed at the same time.

Note: The runtime makes no guarantees about the order on which effects are performed! If you need to chain or sequence effects together, you have two broad options:

1. Create variants of your message type to represent each step in the sequence and fire off the next effect in response to the previous one.

2. If you’re defining effects yourself, consider whether or not you can handle the sequencing inside the effect itself.

Schedule a side effect that is guaranteed to run after your view function is called and the DOM has been updated, but before the browser has painted the screen. This effect is useful when you need to read from the DOM or perform other operations that might affect the layout of your application.

In addition to the dispatch function, your callback will also be provided with root element of your app or component. This is especially useful inside of components, giving you a reference to the Shadow Root.

Messages dispatched immediately in this effect will trigger a second re-render of your application before the browser paints the screen. This let’s you read the state of the DOM, update your model, and then render a second time with the additional information.

Note: dispatching messages synchronously in this effect can lead to degraded performance if not used correctly. In the worst case you can lock up the browser and prevent it from painting the screen at all.

Note: There is no concept of a “paint” for server components. These effects will be ignored in those contexts and never run.

Construct your own reusable effect from a custom callback. This callback is called with a dispatch function you can use to send messages back to your application’s update function.

Example using the window module from the plinth library to dispatch a message on the browser window object’s "visibilitychange" event.

import lustre/effect.{type Effect}
import plinth/browser/window

type Model {
  Model(Int)
}

type message {
  FetchState
}

fn init(_flags) -> #(Model, Effect(message)) {
  #(
    Model(0),
    effect.from(fn(dispatch) {
      window.add_event_listener("visibilitychange", fn(_event) {
        dispatch(FetchState)
      })
    }),
  )
}

Transform the result of an effect. This is useful for mapping over effects produced by other libraries or modules.

Note: Remember that effects are not required to dispatch any messages. Your mapping function may never be called!

Most Lustre applications need to return a tuple of #(model, Effect(message)) from their init and update functions. If you don’t want to perform any side effects, you can use none to tell the runtime there’s no work to do.

Provide a context value to child components in the DOM that this Lustre app didn’t render. This occurs in components with that render one or more <slot> elements in their view function.

Once a value for the given key has been provided, children can subscribe to changes and receive updates any subsequent times provide is called with the same key. This facilitates parent-child communication even in cases where the parent doesn’t own the child element directly.

Note: This is one half of the WCCG Context Protocol and will work in tandem with not just Lustre components but any third-party Web Component that implements the context-request event.

Subscribe to changes for a context value provided by a parent element in the DOM. This effect will decode the context value from the first parent element that has already provided a context for this key at least once. Once a subscription is set up, any changes to the context value will trigger additional messages to be dispatched with the new decoded value.

If no parent elements have provided a context for the given key at the time this effect is run, no subscription is set up even if a parent later provides a context for this key.

Note: Pay attention to timing and lifecycle differences between applications and components. Components that need to subscribe to a context should make sure this effect is called after the component has connected.

Note: This is one half of the WCCG Context Protocol and will work in tandem with not just Lustre components and applications, but any third-party Web Component that acts as a context provider.

Unsubscribe from a context subscription that was previously set up for this key.