lustre

lustre/element

Lustre wouldn’t be much use as a frontend framework if it didn’t provide a way to create HTML elements. This module contains the basic functions necessary to construct and manipulate different HTML elements.

It is also possible to use Lustre as a HTML templating library, without using its runtime or framework features.

Types

Element

</>

The Element type is how Lustre represents chunks of HTML. The msg type variable is used to represent the types of messages that can be produced from events on the element or its children.

Note: Just because an element can produces messages of a given type, doesn’t mean that it will! The msg type variable is used to represent the potential for messages to be produced, not a guarantee.

The most basic ways to create elements are:

  • The element function to construct arbitrary HTML elements. You can also use this render Custom Elements (like those registered as Lustre components).

  • The text function to turn a Gleam string into a text node.

  • The none function to render nothing - useful for conditional rendering.

If you have more complex needs, there are two more-advanced ways to construct HTML elements:

  • The namespaced function to create elements in a specific XML namespace. This is useful for SVG or MathML elements, for example.

  • The advanced function to create elements with more control over how the element is rendered when converted to a string. This is necessary because some HTML, SVG, and MathML elements are self-closing or void elements, and Lustre needs to know how to render them correctly!

Finally, for other niche use cases there are two additional functions:

  • The fragment function lets you wrap a list of Elements up as a single Element, making it useful to avoid wrapping elements in a <div/> or other container when you don’t want to.

  • The unsafe_raw_html function lets you render raw HTML directly into an element. This function is primarily useful in cases where you have pre-sanitised HTML or are working with libraries outside of Lustre that produce plain HTML strings.

    Lustre will not escape the HTML string provided to this functio, meaning inappropriate use can expose your application to XSS attacks. Make sure you never take untrusted user input and pass it to this function!

pub type Element(msg) =
  vnode.Element(msg)

Values

advanced

</> 
pub fn advanced(
  namespace: String,
  tag: String,
  attributes: List(Attribute(a)),
  children: List(Element(a)),
  self_closing: Bool,
  void: Bool,
) -> Element(a)

A function for constructing elements with more control over how the element is rendered when converted to a string. This is necessary because some HTML, SVG, and MathML elements are self-closing or void elements, and Lustre needs to know how to render them correctly!

element

</> 
pub fn element(
  tag: String,
  attributes: List(Attribute(a)),
  children: List(Element(a)),
) -> Element(a)

A general function for constructing any kind of element. In most cases you will want to use the lustre/element/html instead but this function is particularly handy when constructing custom elements, either from your own Lustre components or from external JavaScript libraries.

Note: Because Lustre is primarily used to create HTML, this function special-cases the following tags which render as void elements:

  • area
  • base
  • br
  • col
  • embed
  • hr
  • img
  • input
  • link
  • meta
  • param
  • source
  • track
  • wbr

This will only affect the output of to_string and to_string_builder! If you need to render any of these tags with children, or you want to render some other tag as self-closing or void, use advanced to construct the element instead.

fragment

</> 
pub fn fragment(children: List(Element(a))) -> Element(a)

A function for constructing a wrapper element with no tag name. This is useful for wrapping a list of elements together without adding an extra <div> or other container element, or returning multiple elements in places where only one Element is expected.

map

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

The Element type is parameterised by the type of messages it can produce from events. Sometimes you might end up with a fragment of HTML from another library or module that produces a different type of message: this function lets you map the messages produced from one type to another.

Think of it like list.map or result.map but for HTML events!

namespaced

</> 
pub fn namespaced(
  namespace: String,
  tag: String,
  attributes: List(Attribute(a)),
  children: List(Element(a)),
) -> Element(a)

A function for constructing elements in a specific XML namespace. This can be used to construct SVG or MathML elements, for example.

none

</> 
pub fn none() -> Element(a)

A function for rendering nothing. This is mostly useful for conditional rendering, where you might want to render something only if a certain condition is met.

text

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

A function for turning a Gleam string into a text node. Gleam doesn’t have union types like some other languages you may be familiar with, like TypeScript. Instead, we need a way to take a String and turn it into an Element somehow: this function is exactly that!

to_document_string

</> 
pub fn to_document_string(el: Element(a)) -> String

Converts an element to a string like to_string, but prepends a <!doctype html> declaration to the string. This is useful for rendering complete HTML documents.

If the provided element is not an html element, it will be wrapped in both a html and body element.

to_document_string_tree

</> 
pub fn to_document_string_tree(el: Element(a)) -> StringTree

Converts an element to a StringTree like to_string_builder, but prepends a <!doctype html> declaration. This is useful for rendering complete HTML documents.

If the provided element is not an html element, it will be wrapped in both a html and body element.

to_readable_string

</> 
pub fn to_readable_string(el: Element(a)) -> String

Converts a Lustre Element to a human-readable string by inserting new lines and indentation where appropriate. This is useful for debugging and testing, but for production code you should use to_string or to_document_string instead.

💡 This function works great with the snapshot testing library birdie!

Using to_string:

<header><h1>Hello, world!</h1></header>

Using to_readable_string

<header>
  <h1>
    Hello, world!
  </h1>
</header>

to_string

</> 
pub fn to_string(element: Element(a)) -> String

Convert a Lustre Element to a string. This is not pretty-printed, so there are no newlines or indentation. If you need to pretty-print an element, reach out on the Gleam Discord or open an issue with your use case and we’ll see what we can do!

to_string_tree

</> 
pub fn to_string_tree(element: Element(a)) -> StringTree

Convert a Lustre Element to a StringTree. This is not pretty-printed, so there are no newlines or indentation. If you need to pretty-print an element, reach out on the Gleam Discord or open an issue with your use case and we’ll see what we can do!

unsafe_raw_html

</> 
pub fn unsafe_raw_html(
  namespace: String,
  tag: String,
  attributes: List(Attribute(a)),
  inner_html: String,
) -> Element(a)

A function for constructing a wrapper element with custom raw HTML as its content. Lustre will render the provided HTML verbatim, and will not touch its children except when replacing the entire inner html on changes.

Note: The provided HTML will not be escaped automatically and may expose your applications to XSS attacks! Make sure you absolutely trust the HTML you pass to this function. In particular, never use this to display un-sanitised user HTML!

✨ Search Document