lustre_ui - v1.0.0-rc.1

lustre/ui/button

The button element is a clickable control that receives keyboard and pointer events that you would use to dispatch messages to your update function when interacted with.

Common uses for buttons include:

Anatomy

A button is made up of different parts:

Recipes

Below are some recipes that show common uses of the button element.

A basic button with an icon and text:

import lustre/element/html
import lustre/event
import lustre/ui/button.{button}
import lustre/ui/icon

pub fn save(handle_click) {
  button([event.on_click(handle_click)], [
    icon.save([]),
    html.text("Save"),
  ])
}

A command palette button with a keyboard shortcut badge:

import lustre/element/html
import lustre/event
import lustre/ui/button.{button}

pub fn command_palette(handle_click) {
  button([button.solid(), event.on_click(handle_click)], [
    html.text("Open"),
    button.shortcut_badge([], ["⌘", "k"])
  ])
}

Customisation

The style or look of a button can be controlled by using one of the following attributes:

The size of a button can be controlled by using one of the following attributes:

The border radius of a button can be controlled while still using your theme’s configuration by using one of the following attributes:

It is possible to control some aspects of a button’s styling through CSS variables. You may want to do this in cases where you are integrating lustre/ui into an existing design system and you want the button element to match elements outside of this package.

The following CSS variables can set in your own stylesheets or by using the corresponding attribute functions in this module:

Functions

background

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

background_hover

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

badge

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

Renders a small badge inside a button. Badges are used to display additional information such as a keyboard shortcut or a count of items.

border

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

border_hover

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

border_width

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

button

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

The button element is a clickable control that receives keyboard and pointer events that you would use to dispatch messages to your update function when interacted with.

Note: in Safari, buttons aren’t part of the tab order by default. To make them focusable, buttons in Lustre UI have their tabindex attribute set to 0 for consistent behaviour across browsers.

clear

</> 
pub fn clear() -> Attribute(a)

count_badge

</> 
pub fn count_badge(
  attributes: List(Attribute(a)),
  count: Int,
) -> Element(a)

Renders a small numerical count as a badge inside a button. This could be used to represent the number of items in a list or the number of unread notifications.

If the count is greater than 99, the badge will display "99+".

height

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

icon

</> 
pub fn icon() -> Attribute(a)

large

</> 
pub fn large() -> Attribute(a)
</> 
pub fn link(
  attributes: List(Attribute(a)),
  children: List(Element(a)),
) -> Element(a)

Styles a HTML <a> element as a button. You should use this element when you want to create a button that navigates to a different page or location.

medium

</> 
pub fn medium() -> Attribute(a)

min_height

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

of

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

In the uncommon case that you need to render a button as a different HTML element, you can use this function to supply the element you want to use. This can be useful if you have an element that implements the functionality of a button but and you to add Lustre UI’s button styles to it.

Note: If you are styling a different element as a button, it’s crucial to ensure that the element is accessible and behaves correctly. In most cases, this means setting the role attribute to "button" and ensuring that the element handles both click and keyboard events.

outline

</> 
pub fn outline() -> Attribute(a)

padding_x

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

pill

</> 
pub fn pill() -> Attribute(a)

radius

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

round

</> 
pub fn round() -> Attribute(a)

shortcut_badge

</> 
pub fn shortcut_badge(
  attributes: List(Attribute(a)),
  chord: List(String),
) -> Element(a)

Renders a small badge inside a button that represents a keyboard shortcut that would trigger the button’s action.

You can add a separator between keys by setting the --separator css variable:

import lustre/attribute
import lustre/ui/button

pub fn cmd_k_badge() {
  let chord = ["⌘", "k"]
  let styles = attribute.style([#("--separator", "'+'")])

  button.shortcut_badge([styles], chord)
}

small

</> 
pub fn small() -> Attribute(a)

soft

</> 
pub fn soft() -> Attribute(a)

solid

</> 
pub fn solid() -> Attribute(a)

square

</> 
pub fn square() -> Attribute(a)

text

</> 
pub fn text(value: String) -> Attribute(a)
✨ Search Document