Describing the UI

Dioxus is a declarative framework. This means that instead of telling Dioxus what to do (e.g. to "create an element" or "set the color to red") we simply declare what we want the UI to look like using RSX.

You have already seen a simple example of RSX syntax in the "hello world" application:

// define a component that renders a div with the text "Hello, world!"
fn App(cx: Scope) -> Element {
    cx.render(rsx! {
        div {
            "Hello, world!"
        }
    })
}

Here, we use the rsx! macro to declare that we want a div element, containing the text "Hello, world!". Dioxus takes the RSX and constructs a UI from it.

RSX Features

RSX is very similar to HTML in that it describes elements with attributes and children. Here's an empty div element in RSX, as well as the resulting HTML:

cx.render(rsx!(div {
    // attributes / listeners
    // children
}))

Attributes

Attributes (and event handlers) modify the behavior or appearance of the element they are attached to. They are specified inside the {} brackets, using the name: value syntax. You can provide the value as a literal in the RSX:

cx.render(rsx!(img {
    src: "https://avatars.githubusercontent.com/u/79236386?s=200&v=4",
    class: "primary_button",
    width: "10px"
}))

Note: All attributes defined in dioxus-html follow the snake_case naming convention. They transform their snake_case names to HTML's camelCase attributes.

Note: Styles can be used directly outside of the style: attribute. In the above example, color: "red" is turned into style="color: red".

Custom Attributes

Dioxus has a pre-configured set of attributes that you can use. RSX is validated at compile time to make sure you didn't specify an invalid attribute. If you want to override this behavior with a custom attribute name, specify the attribute in quotes:

cx.render(rsx!(div {
    "style": "width: 20px; height: 20px; background-color: red;",
}))

Special Attributes

While most attributes are simply passed on to the HTML, some have special behaviors.

The HTML Escape Hatch

If you're working with pre-rendered assets, output from templates, or output from a JS library, then you might want to pass HTML directly instead of going through Dioxus. In these instances, reach for dangerous_inner_html.

For example, shipping a markdown-to-Dioxus converter might significantly bloat your final application size. Instead, you'll want to pre-render your markdown to HTML and then include the HTML directly in your output. We use this approach for the Dioxus homepage:

// this should come from a trusted source
let contents = "live <b>dangerously</b>";

cx.render(rsx! {
    div {
        dangerous_inner_html: "{contents}",
    }
})

Note! This attribute is called "dangerous_inner_html" because it is dangerous to pass it data you don't trust. If you're not careful, you can easily expose cross-site scripting (XSS) attacks to your users.

If you're handling untrusted input, make sure to sanitize your HTML before passing it into dangerous_inner_html – or just pass it to a Text Element to escape any HTML tags.

Boolean Attributes

Most attributes, when rendered, will be rendered exactly as the input you provided. However, some attributes are considered "boolean" attributes and just their presence determines whether they affect the output. For these attributes, a provided value of "false" will cause them to be removed from the target element.

So this RSX wouldn't actually render the hidden attribute:

cx.render(rsx! {
    div {
        hidden: false,
        "hello"
    }
})

Not all attributes work like this however. Only the following attributes have this behavior:

• allowfullscreen
• allowpaymentrequest
• async
• autofocus
• autoplay
• checked
• controls
• default
• defer
• disabled
• formnovalidate
• hidden
• ismap
• itemscope
• loop
• multiple
• muted
• nomodule
• novalidate
• open
• playsinline
• readonly
• required
• reversed
• selected
• truespeed

For any other attributes, a value of "false" will be sent directly to the DOM.

Interpolation

Similarly to how you can format Rust strings, you can also interpolate in RSX text. Use {variable} to Display the value of a variable in a string, or {variable:?} to use the Debug representation:

let coordinates = (42, 0);
let country = "es";
cx.render(rsx!(div {
    class: "country-{country}",
    left: "{coordinates.0:?}",
    top: "{coordinates.1:?}",
    // arbitrary expressions are allowed,
    // as long as they don't contain `{}`
    div {
        "{country.to_uppercase()}"
    },
    div {
        "{7*6}"
    },
    // {} can be escaped with {{}}
    div {
        "{{}}"
    },
}))

Children

To add children to an element, put them inside the {} brackets after all attributes and listeners in the element. They can be other elements, text, or components. For example, you could have an ol (ordered list) element, containing 3 li (list item) elements, each of which contains some text:

cx.render(rsx!(ol {
    li {"First Item"}
    li {"Second Item"}
    li {"Third Item"}
}))

Fragments

You can render multiple elements at the top level of rsx! and they will be automatically grouped.

cx.render(rsx!(
    p {"First Item"},
    p {"Second Item"},
))

Expressions

You can include arbitrary Rust expressions as children within RSX that implements IntoDynNode. This is useful for displaying data from an iterator:

let text = "Dioxus";
cx.render(rsx!(span {
    text.to_uppercase(),
    // create a list of text from 0 to 9
    (0..10).map(|i| rsx!{ i.to_string() })
}))

Loops

In addition to iterators you can also use for loops directly within RSX:

cx.render(rsx! {
    // use a for loop where the body itself is RSX
    div {
        // create a list of text from 0 to 9
        for i in 0..3 {
            // NOTE: the body of the loop is RSX not a rust statement
            div {
                "{i}"
            }
        }
    }
    // iterator equivalent
    div {
        (0..3).map(|i| rsx!{ div { "{i}" } })
    }
})

If statements

You can also use if statements without an else branch within RSX:

cx.render(rsx! {
    // use if statements without an else
    if true {
        rsx!(div { "true" })
    }
})