dioxus-html: Html (and SVG) Namespace for Dioxus

Website | Guides | API Docs | Chat

Overview

The Dioxus rsx! macro can accept any compile-time correct namespace on top of NodeFactory. This crate provides the HTML (and SVG) namespaces which get imported in the Dioxus prelude.

However, this abstraction enables you to add any namespace of elements, provided they're in scope when rsx! is called. For an example, a UI that is designed for Augmented Reality might use different primitives than HTML:

use ar_namespace::*;

rsx! {
    magic_div {
        magic_header {}
        magic_paragraph {
            on_magic_click: move |event| {
                //
            }
        }
    }
}

This typed-builder system makes it possible to provide syntax highlighting, documentation, "go to definition" and compile-time correctness for elements and their attributes.

How it works:

Every HTML element is generated by the [define_elements!] macro. For each element the macro emits a builder whose methods are that element's attributes, so the rsx! macro lowers an element to the same typed builder path it uses for components.

Attributes shared by every element — global attributes (class, id, hidden, ...) and event handlers (onclick, ...) — are provided through extension traits rather than being redefined on each tag. The built-in ones live under dioxus_html::extensions (GlobalAttributesExtension, SvgAttributesExtension, EventsExtension, and per-element extensions). Because each attribute is a typed method that records its serialized name and namespace, attribute creation is guarded behind a compile-time-correct interface.

Since elements are builders generated by a macro rather than items in a fixed namespace, you can define your own elements from user code with the same macro — the built-in HTML vocabulary is defined this way too. See "How to extend it" below.

How to extend it:

Whenever the rsx! macro is called, it relies on the HTML element constructors and extension traits that are in scope. When you enable the html feature in dioxus, the prelude imports the built-in HTML namespace for you. You can extend this with your own custom elements by adding a constructor for the tag and extension traits for any typed attributes you want to support.

dioxus::html::define_elements! {
    #[element(name = "analytics-panel")]
    analyticsPanel {
        metric,
        #[attr(name = "data-region")]
        region,
    }
}

rsx! {
    analyticsPanel {
        class: "metric-card",
        metric: "conversion-rate",
        region: "north-america",
        "Rendered as <analytics-panel>"
    }
}

See examples/09-reference/custom_element.rs for a complete example.

Contributing

• Report issues on our issue tracker.
• Join the discord and ask questions!

License

This project is licensed under the MIT license.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you shall be licensed as MIT without any additional terms or conditions.