Skip to main content
Version: Next

Low-level library internals

Under the hood of the html! macro​

The html! macro turns code written in a custom HTML-like syntax into valid Rust code. Using this macro is not necessary for developing Yew applications, but it is recommended. The code generated by this macro makes use of the public Yew library API which can be used directly if you wish. Note that some methods used are undocumented intentionally to avoid accidental misuse. With each update of yew-macro, the generated code will be more efficient and handle any breaking changes without many (if any) modifications to the html! syntax.

Because the html! macro allows you to write code in a declarative style, your UI layout code will closely match the HTML that is generated for the page. This becomes increasingly useful as your application gets more interactive and your codebase gets larger. Rather than manually writing all of the code to manipulate the DOM yourself, the macro will handle it for you.

Using the html! macro can feel pretty magical, but it has nothing to hide. If you are curious about how it works, try expanding the html! macro calls in your program. There is a useful command called cargo expand which allows you to see the expansion of Rust macros. cargo expand does not ship with cargo by default so you will need to install it with cargo install cargo-expand if you have not already. Rust-Analyzer also provides a mechanism for obtaining macro output from within an IDE.

Output from the html! macro is often pretty terse! This is a feature: machine-generated code can sometimes clash with other code in an application. To prevent issues, proc_macro "hygiene" is adhered to. Some examples include:

  1. Instead of using yew::<module> the macro generates ::yew::<module> to make sure that the Yew package is referenced correctly. This is also why ::alloc::vec::Vec::new() is called instead of just Vec::new().
  2. Due to potential trait method name collisions, <Type as Trait> is used to make sure that we are using members from the correct trait.

What is a virtual DOM?​

The DOM ("document object model") is a representation of the HTML content that is managed by the browser for your web page. A "virtual" DOM is simply a copy of the DOM that is held in application memory. Managing a virtual DOM results in a higher memory overhead, but allows for batching and faster reads by avoiding or delaying the use of browser APIs.

Having a copy of the DOM in memory can be helpful for libraries that promote the use of declarative UIs. Rather than needing specific code for describing how the DOM should be modified in response to a user event, the library can use a generalized approach with DOM "diffing". When a Yew component is updated and wants to change how it is rendered, the Yew library will build a second copy of the virtual DOM and directly compare it to a virtual DOM which mirrors what is currently on screen. The "diff" (or difference) between the two can be broken down into incremental updates and applied in a batch with browser APIs. Once the updates are applied, the old virtual DOM copy is discarded and the new copy is saved for future diff checks.

This "diff" algorithm can be optimized over time to improve the performance of complex applications. Since Yew applications are run with WebAssembly, we believe that Yew has a competitive edge to adopt more sophisticated algorithms in the future.

The Yew virtual DOM is not exactly one-to-one with the browser DOM. It also includes "lists" and "components" for organizing DOM elements. A list can simply be an ordered list of elements but can also be much more powerful. By annotating each list element with a "key", application developers can help Yew make additional optimizations to ensure that when a list changes, the least amount of work is done to calculate the diff update. Similarly, components provide custom logic to indicate whether a re-render is required to help with performance.

Yew scheduler and component-scoped event loop​

Contribute to the docs – explain how yew::scheduler and yew::html::scope work in depth

Further reading​