lustre - v3.0.0-rc.8

lustre/attribute

Types

Attribute

</>

Attributes are attached to specific elements. They’re either key/value pairs or event handlers.

pub opaque type Attribute(msg)

Functions

accept

</> 
pub fn accept(types: List(String)) -> Attribute(a)

accept_charset

</> 
pub fn accept_charset(types: List(String)) -> Attribute(a)

alt

</> 
pub fn alt(text: String) -> Attribute(a)

attribute

</> 
pub fn attribute(name: String, value: String) -> Attribute(a)

Lustre does some work internally to convert common Gleam values into ones that make sense for JavaScript. Here are the types that are converted:

  • List(a) -> Array(a)
  • Some(a) -> a
  • None -> undefined

autocomplete

</> 
pub fn autocomplete(name: String) -> Attribute(a)

autofocus

</> 
pub fn autofocus(should_autofocus: Bool) -> Attribute(a)

autoplay

</> 
pub fn autoplay(should_autoplay: Bool) -> Attribute(a)

checked

</> 
pub fn checked(is_checked: Bool) -> Attribute(a)

class

</> 
pub fn class(name: String) -> Attribute(a)

classes

</> 
pub fn classes(names: List(#(String, Bool))) -> Attribute(a)

cols

</> 
pub fn cols(val: Int) -> Attribute(a)

controls

</> 
pub fn controls(visible: Bool) -> Attribute(a)

disabled

</> 
pub fn disabled(is_disabled: Bool) -> Attribute(a)

download

</> 
pub fn download(filename: String) -> Attribute(a)

for

</> 
pub fn for(id: String) -> Attribute(a)

height

</> 
pub fn height(val: Int) -> Attribute(a)

href

</> 
pub fn href(uri: String) -> Attribute(a)

id

</> 
pub fn id(name: String) -> Attribute(a)

loop

</> 
pub fn loop(should_loop: Bool) -> Attribute(a)

map

</> 
pub fn map(attr: Attribute(a), f: fn(a) -> b) -> Attribute(b)

max

</> 
pub fn max(val: String) -> Attribute(a)

min

</> 
pub fn min(val: String) -> Attribute(a)

msg

</> 
pub fn msg(uri: String) -> Attribute(a)

name

</> 
pub fn name(name: String) -> Attribute(a)

on

</> 
pub fn on(name: String, handler: fn(Dynamic) -> Option(a)) -> Attribute(
  a,
)

Attach custom event handlers to an element. A number of helper functions exist in this module to cover the most common events and use-cases, so you should check those out first.

If you need to handle an event that isn’t covered by the helper functions, then you can use on to attach a custom event handler. The callback is given the event object as a Dynamic.

As a simple example, you can implement on_click like so:

import gleam/option.{Some}
import lustre/attribute.{Attribute}
import lustre/event

pub fn on_click(msg: msg) -> Attribute(msg) {
  use _ <- event.on("click")
  Some(msg)
}

By using gleam/dynamic you can decode the event object and pull out all sorts of useful data. This is how on_input is implemented:

import gleam/dynamic
import gleam/option.{None, Some}
import gleam/result
import lustre/attribute.{Attribute}
import lustre/event

pub fn on_input(msg: fn(String) -> msg) -> Attribute(msg) {
  use event, dispatch <- on("input")
  let decode = dynamic.field("target", dynamic.field("value", dynamic.string))

  case decode(event) {
    Ok(value) -> Some(msg(value))
    Error(_) -> None
  }
}

You can take a look at the MDN reference for events here to see what you can decode.

Unlike the helpers in the rest of this module, it is possible to simply ignore the dispatch function and not dispatch a message at all. In fact, we saw this with the on_input example above: if we can’t decode the event object, we simply return None and emit nothing.

Beyond ignoring errors, this can be used to perform side effects we don’t need to observe in our main application loop, such as logging…

import gleam/io
import gleam/option.{None}
import lustre/attribute.{Attribute}
import lustre/event

pub fn log_on_click(msg: String) -> Attribute(msg) {
  use _ <- event.on("click")
  io.println(msg)
  None
}

pattern

</> 
pub fn pattern(regex: String) -> Attribute(a)

placeholder

</> 
pub fn placeholder(text: String) -> Attribute(a)

property

</> 
pub fn property(name: String, value: a) -> Attribute(b)

readonly

</> 
pub fn readonly(is_readonly: Bool) -> Attribute(a)

rel

</> 
pub fn rel(relationship: String) -> Attribute(a)

required

</> 
pub fn required(is_required: Bool) -> Attribute(a)

rows

</> 
pub fn rows(val: Int) -> Attribute(a)

selected

</> 
pub fn selected(is_selected: Bool) -> Attribute(a)

src

</> 
pub fn src(uri: String) -> Attribute(a)

step

</> 
pub fn step(val: String) -> Attribute(a)

style

</> 
pub fn style(properties: List(#(String, String))) -> Attribute(a)

target

</> 
pub fn target(target: String) -> Attribute(a)

to_string

</> 
pub fn to_string(attr: Attribute(a)) -> String

to_string_builder

</> 
pub fn to_string_builder(attr: Attribute(a)) -> StringBuilder

type_

</> 
pub fn type_(name: String) -> Attribute(a)

value

</> 
pub fn value(val: Dynamic) -> Attribute(a)

width

</> 
pub fn width(val: Int) -> Attribute(a)

wrap

</> 
pub fn wrap(mode: String) -> Attribute(a)
✨ Search Document