# `dioxus-html`: Html (and SVG) Namespace for Dioxus
[![Crates.io][crates-badge]][crates-url]
[![MIT licensed][mit-badge]][mit-url]
[![Build Status][actions-badge]][actions-url]
[![Discord chat][discord-badge]][discord-url]
[crates-badge]: https://img.shields.io/crates/v/dioxus-html.svg
[crates-url]: https://crates.io/crates/dioxus-html
[mit-badge]: https://img.shields.io/badge/license-MIT-blue.svg
[mit-url]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT
[actions-badge]: https://github.com/dioxuslabs/dioxus/actions/workflows/main.yml/badge.svg
[actions-url]: https://github.com/dioxuslabs/dioxus/actions?query=workflow%3ACI+branch%3Amaster
[discord-badge]: https://img.shields.io/discord/899851952891002890.svg?logo=discord&style=flat-square
[discord-url]: https://discord.gg/XgGxMSkvUM
[Website](https://dioxuslabs.com) |
[Guides](https://dioxuslabs.com/learn/0.7/) |
[API Docs](https://docs.rs/dioxus-html/latest/dioxus_html) |
[Chat](https://discord.gg/XgGxMSkvUM)
## 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:
```rust, ignore
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.
```rust, ignore
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`](../../examples/09-reference/custom_element.rs) for a complete example.
## Contributing
- Report issues on our [issue tracker](https://github.com/dioxuslabs/dioxus/issues).
- Join the discord and ask questions!
## License
This project is licensed under the [MIT license].
[mit license]: https://github.com/dioxuslabs/dioxus/blob/main/LICENSE-MIT
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.