Skip to main content
Version: 0.19.0

HTML

The html! macro allows you to write HTML and SVG code declaratively. It is similar to JSX (an extension to JavaScript which allows you to write HTML-like code inside of JavaScript).

Important notes

  1. The html! macro only accepts one root html node (you can counteract this by using fragments or iterators)
  2. An empty html! {} invocation is valid and will not render anything
  3. Literals must always be quoted and wrapped in braces: html! { "Hello, World" }
  4. The html! macro will make all tag names lowercase. To use uppercase characters (which are required for some SVG elements) you must use VTag::new to create elements directly and add attributes and children manually instead of using the macro. There is a more ergonomic solution to this in Yew Next.
note

The html! macro can reach the default recursion limit of the compiler. If you encounter compilation errors, add an attribute like #![recursion_limit="1024"] in the crate root to overcome the problem.

Tag Structure​

Tags are based on HTML tags. Components, Elements, and Lists are all based on this tag syntax.

Tags must either self-close <... /> or have a corresponding end tag for each start tag.

use yew::html;

html! {
  <div id="my_div"></div>
};
use yew::html;

html! {
  <input id="my_input" />
};
tip

For convenience, elements which usually require a closing tag are allowed to self-close. For example, writing html! { <div class="placeholder" /> } is valid.

Children​

Create complex nested HTML and SVG layouts with ease:

use yew::html;

html! {
    <div>
        <div data-key="abc"></div>
        <div class="parent">
            <span class="child" value="anything"></span>
            <label for="first-name">{ "First Name" }</label>
            <input type="text" id="first-name" value="placeholder" />
            <input type="checkbox" checked=true />
            <textarea value="write a story" />
            <select name="status">
                <option selected=true disabled=false value="">{ "Selected" }</option>
                <option selected=false disabled=true value="">{ "Unselected" }</option>
            </select>
        </div>
    </div>
};

Lints​

If you compile Yew using a nightly version of the Rust compiler, the macro will warn you about some common pitfalls that you might run into. Of course, you may need to use the stable compiler (e.g. your organization might have a policy mandating it) for release builds, but even if you're using a stable toolchain, running cargo +nightly check might flag some ways that you could improve your HTML code.

At the moment the lints are mostly accessibility-related. If you have ideas for lints, please feel free to chime in on this issue.

Special properties​

There are special properties which don't directly influence the DOM but instead act as instructions to Yew's virtual DOM. Currently, there are two such special props: ref and key.

ref allows you to access and manipulate the underlying DOM node directly. See Refs for more details.

key on the other hand gives an element a unique identifier which Yew can use for optimization purposes.

important

The documentation for keys is yet to be written. See #1263.

For now, use keys when you have a list where the order of elements changes. This includes inserting or removing elements from anywhere but the end of the list.

If blocks​

To conditionally render some markup, we wrap it in an if block:

use yew::html;

html! {
    if true {
        <p>{ "True case" }</p>
    }
};