lustre - v2.0.0

lustre/element

Types

Element

</> 
pub external type Element(msg)

Functions

a

</> 
pub fn a(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

abbr

</> 
pub fn abbr(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

address

</> 
pub fn address(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

area

</> 
pub fn area(attrs: List(Attribute(a))) -> Element(a)

article

</> 
pub fn article(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

aside

</> 
pub fn aside(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

audio

</> 
pub fn audio(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

b

</> 
pub fn b(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

base

</> 
pub fn base(attrs: List(Attribute(a))) -> Element(a)

bdi

</> 
pub fn bdi(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

bdo

</> 
pub fn bdo(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

blockquote

</> 
pub fn blockquote(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

body

</> 
pub fn body(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

br

</> 
pub fn br(attrs: List(Attribute(a))) -> Element(a)

button

</> 
pub fn button(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

canvas

</> 
pub fn canvas(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

caption

</> 
pub fn caption(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

cite

</> 
pub fn cite(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

code

</> 
pub fn code(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

col

</> 
pub fn col(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

colgroup

</> 
pub fn colgroup(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

datalist

</> 
pub fn datalist(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

dd

</> 
pub fn dd(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

del

</> 
pub fn del(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

details

</> 
pub fn details(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

dfn

</> 
pub fn dfn(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

dialog

</> 
pub fn dialog(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

div

</> 
pub fn div(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

dl

</> 
pub fn dl(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

dt

</> 
pub fn dt(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

em

</> 
pub fn em(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

embed

</> 
pub fn embed(attrs: List(Attribute(a))) -> Element(a)

fieldset

</> 
pub fn fieldset(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

figcaption

</> 
pub fn figcaption(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

figure

</> 
pub fn figure(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)
</> 
pub fn footer(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

form

</> 
pub fn form(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

fragment

</> 
pub external fn fragment(
  children: List(Element(msg)),
) -> Element(msg)

A fragment doesn’t appear in the DOM, but allows us to treat a list of elements as if it were a single one.

h1

</> 
pub fn h1(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

h2

</> 
pub fn h2(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

h3

</> 
pub fn h3(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

h4

</> 
pub fn h4(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

h5

</> 
pub fn h5(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

h6

</> 
pub fn h6(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)
</> 
pub fn head(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)
</> 
pub fn header(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

hr

</> 
pub fn hr(attrs: List(Attribute(a))) -> Element(a)

html

</> 
pub fn html(attrs: List(Attribute(a)), head: Element(a), body: Element(
    a,
  )) -> Element(a)

i

</> 
pub fn i(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

iframe

</> 
pub fn iframe(attrs: List(Attribute(a))) -> Element(a)

img

</> 
pub fn img(attrs: List(Attribute(a))) -> Element(a)

input

</> 
pub fn input(attrs: List(Attribute(a))) -> Element(a)

ins

</> 
pub fn ins(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

kbd

</> 
pub fn kbd(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

label

</> 
pub fn label(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

legend

</> 
pub fn legend(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

li

</> 
pub fn li(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

main

</> 
pub fn main(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

map

</> 
pub external fn map(
  element: Element(a),
  f: fn(a) -> b,
) -> Element(b)

Transforms the actions produced by an element. Our Lustre applications have a single top-level Msg type and update function, and ultimately all elements we create must produce actions of that type (or not produce any at all).

To save us having a monolothic Msg type with many constructors, we can crete child types and then use map to wrap them up in the parent type. A simple counter with its own message type my look like this:

import gleam/int
import lustre/element.{Element}
import lustre/event

type Msg {
  Decr
  Incr
}

pub fn update(count: Int, msg: CounterMsg) -> Int {
  case msg {
    Decr -> count - 1
    Incr -> count + 1
  }
}

pub fn render(count: Int) -> Element(CounterMsg) {
  element.div([], [
    element.button([event.on_click(Decr)], [element.text("-")]),
    element.text(int.to_string(count)),
    element.button([event.on_click(Incr)], [element.text("+")]),
  ])
}

To integrate this into a large Lustre application, we need to do some plumbing. Here’s how we might have a parent application that renders multiple counters:

import counter.{Msg as CounterMsg}
import gleam/list
import gleam/map.{Map}
import gleam/result
import lustre
import lustre/element.{Element}
import lustre/event

pub fn main() {
  let app = lustre.simple(init(), update, render)
  assert Ok(_) = lustre.start(app, "#root")
}

type Model = Map(Int, Int)

fn init() -> Model {
  map.from_list([
    #(0, 0),
    #(1, 0),
    #(2, 0),
  ])
}

type Msg {
  UpdateCounter(Int, CounterMsg)
}

pub fn update(model: Model, msg: Msg) -> Model {
  case msg {
    UpdateCounter(id, counter_msg) -> {
      map.get(model, id)
      // Call the counter's update function with the `counter_msg`. This will
      // either be `counter.Decr` or `counter.Incr`.
      |> result.map(counter.update(_, counter_msg))
      |> result.map(map.insert(model, id, _))
      |> result.unwrap(model)
    }
  }
}

pub fn render(model: Model) -> Element(Msg) {
  let counters = {
    use els, id, count <- map.fold(model, [])
    let counter = counter.render(counr)

    // Right now `counter` produces messages of type `counter.Msg`. Here we're
    // calling `element.map` to wrap that message in our main app's `Msg` type.
    [element.map(counter, UpdateCounter(id, _)), ...els]
  }

  element.div([], list.reverse(counters))
}

If this feels like a lt of work… sometimes it is! Take a look at the docs for stateful elements to see how all this can be encapsulated.

map_

</> 
pub fn map_(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

mark

</> 
pub fn mark(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

mathml

</> 
pub fn mathml(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)
</> 
pub fn menu(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

meta

</> 
pub fn meta(attrs: List(Attribute(a))) -> Element(a)

meter

</> 
pub fn meter(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)
</> 
pub fn nav(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

node

</> 
pub external fn node(
  tag: String,
  attrs: List(Attribute(msg)),
  children: List(Element(msg)),
) -> Element(msg)

Construct a plain HTML element or registered Web Component by providing the tag name, a list of attributes (including event handlers), and a list of child elements.

noscript

</> 
pub fn noscript(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

object

</> 
pub fn object(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

ol

</> 
pub fn ol(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

optgroup

</> 
pub fn optgroup(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

option

</> 
pub fn option(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

output

</> 
pub fn output(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

p

</> 
pub fn p(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

param

</> 
pub fn param(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

picture

</> 
pub fn picture(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

portal

</> 
pub fn portal(attrs: List(Attribute(a))) -> Element(a)

pre

</> 
pub fn pre(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

progress

</> 
pub fn progress(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

rp

</> 
pub fn rp(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

rt

</> 
pub fn rt(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

ruby

</> 
pub fn ruby(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

s

</> 
pub fn s(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

samp

</> 
pub fn samp(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

section

</> 
pub fn section(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

select

</> 
pub fn select(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

slot

</> 
pub fn slot(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

small

</> 
pub fn small(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

source

</> 
pub fn source(attrs: List(Attribute(a))) -> Element(a)

span

</> 
pub fn span(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

stateful

</> 
pub external fn stateful(
  init: state,
  render: fn(state, fn(state) -> Nil) -> Element(msg),
) -> Element(msg)

A stateful element is exactly what it sounds like: an element with local encapsulated state! The render function we must provide is called with the element’s current state as well as a function to set a new state. Whenever that function is called, the element is re-rendered.

You might be wondering where the stateless version of this function is. Those are just regular Gleam functions that return Elements!

We can implement a counter whose current value is stored locally like so:

import gleam/int
import lustre/attribute.{Attribute}
import lustre/element.{Element}
import lustre/event

pub fn counter() -> Element(msg) {
  use state, set_state = lustre.stateful(0)

  let decr = event.on("click", fn(_, _) { set_state(state - 1) })
  let incr = event.on("click", fn(_, _) { set_state(state + 1) })

  element.div([], [
    element.button([decr], [element.text("-")]),
    element.text(int.to_string(state)),
    element.button([incr], [element.text("+")]),
  ])
}

We can use this counter element anywhere in our app, we don’t have to worry about passing state around or managing it in a parent component.

When attaching event handlers to stateful elements, you’ll typically have to use the generic event.on function rather than the more specific helpders. The helpers are designed to emit messages for your application, but stateful elements don’t necessarily produce messages: calling set_state is a side effect.

strong

</> 
pub fn strong(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

style

</> 
pub fn style(attrs: List(Attribute(a)), css: String) -> Element(a)

sub

</> 
pub fn sub(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

summary

</> 
pub fn summary(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

sup

</> 
pub fn sup(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

svg

</> 
pub fn svg(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

table

</> 
pub fn table(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

tbody

</> 
pub fn tbody(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

td

</> 
pub fn td(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

template

</> 
pub fn template(attrs: List(Attribute(a)), children: List(
    Element(a),
  )) -> Element(a)

text

</> 
pub external fn text(content: String) -> Element(msg)

Render a Gleam string as an HTML text node.

textarea

</> 
pub fn textarea(attrs: List(Attribute(a))) -> Element(a)

tfoot

</> 
pub fn tfoot(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

th

</> 
pub fn th(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

thead

</> 
pub fn thead(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

time

</> 
pub fn time(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

title

</> 
pub fn title(attrs: List(Attribute(a)), name: String) -> Element(
  a,
)

tr

</> 
pub fn tr(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

track

</> 
pub fn track(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

u

</> 
pub fn u(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

ul

</> 
pub fn ul(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

var_

</> 
pub fn var_(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

video

</> 
pub fn video(attrs: List(Attribute(a)), children: List(Element(a))) -> Element(
  a,
)

wbr

</> 
pub fn wbr(attrs: List(Attribute(a))) -> Element(a)
✨ Search Document