Crate custom_element

source ·
Expand description

§About custom-element

custom-element provides a CustomElement trait that, when implemented, allows your Rust struct to be rendered as a web component on any html page.

Web components are a great way to eliminate frontend framework lock-in. They are also a great way to bridge the divide between UI components written in JavaScript and UI elements written in Rust.

§Learn By Example

If you want to see some examples of writing web components in Rust, check out examples directory:

  • hello_world is the most basic web component you can create
  • counter is the standard counter example, showing how to re-render in response to events in pure Rust.
  • leptos_in_react shows how you can mix Rust and JavaScript in the same codebase, and even mix Rust/JavaScript frameworks.

§A Simple Hello World

struct HelloWorld;

// all custom element lifecycle hooks have a default no-op implementation
impl CustomElement for HelloWorld {}

impl HelloWorld {
    // called from the JavaScript custom element's `constructor`
    fn new(instance: JsValue, _args: Array) -> Self {
        let instance: HtmlElement = instance.into();
        instance.set_text_content(Some("Hello, world!"));
        HelloWorld
    }
}

fn main() {
    // create custom element constructor
    let component_name = "hello-world";
    let (closure, constructor) = custom_element::create_custom_element(HelloWorld::new, vec![]);

    // we want the Rust code for our custom element to live forever
    closure.forget();

    // define the element
    let window = web_sys::window().unwrap();
    window
        .custom_elements()
        .define(component_name, &constructor)
        .unwrap();

    // render in the DOM
    let body = window.document().unwrap().body().unwrap();
    body.set_inner_html(&format!("<{0}></{0}>", component_name));
}

Modules§

  • constructors
    These are all the valid HTMLElement constructors, exported for convenience. These can be used to created cutomized built-in custom elements.

Structs§

  • CustomElementConfiguration
    Allows specifying details about how your custom element should be created. Currently, this is limited to specifying which constructor function your custom element should inherit from.
  • CustomElementResult
    The result of creating a custom element.
  • GeneratedConstructor
    Wrapper type around the JavaScript GeneratedCustomElement class for easier/more ergonomic calling/conversions

Traits§

  • CustomElement
    This trait is the focal point of this crate, and implementing it allows your Rust struct to be used as a custom element.

Functions§