\n
\n````\n\n### Children\n\nTo 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](components.md). For example, you could have an `ol` (ordered list) element, containing 3 `li` (list item) elements, each of which contains some text:\n\n````rust@rsx_overview.rs\ncx.render(rsx!(ol {\nli {\"First Item\"}\nli {\"Second Item\"}\nli {\"Third Item\"}\n}))\n````\n\n````html\nES
\n 42
\n {}
\n- \n
- First Item \n
- Second Item \n
- Third Item \n
First Item
\nSecond Item
\n````\n\n### Expressions\n\nYou can include arbitrary Rust expressions as children within RSX that implements [IntoDynNode](https://docs.rs/dioxus-core/0.3/dioxus_core/trait.IntoDynNode.html). This is useful for displaying data from an [iterator](https://doc.rust-lang.org/stable/book/ch13-02-iterators.html#processing-a-series-of-items-with-iterators):\n\n````rust@rsx_overview.rs\nlet text = \"Dioxus\";\ncx.render(rsx!(span {\ntext.to_uppercase(),\n// create a list of text from 0 to 9\n(0..10).map(|i| rsx!{ i.to_string() })\n}))\n````\n\n````html\nDIOXUS0123456789\n````\n\n### Loops\n\nIn addition to iterators you can also use for loops directly within RSX:\n\n````rust@rsx_overview.rs\ncx.render(rsx!{\n// use a for loop where the body itself is RSX\ndiv {\n // create a list of text from 0 to 9\n for i in 0..3 {\n // NOTE: the body of the loop is RSX not a rust statement\n div {\n \"{i}\"\n }\n }\n}\n// iterator equivalent\ndiv {\n (0..3).map(|i| rsx!{ div { \"{i}\" } })\n}\n})\n````\n\n````html\n0
\n1
\n2
\n0
\n1
\n2
\n````\n\n### If statements\n\nYou can also use if statements without an else branch within RSX:\n\n````rust@rsx_overview.rs\ncx.render(rsx!{\n// use if statements without an else\nif true {\n rsx!(div { \"true\" })\n}\n})\n````\n\n````html\ntrue
\n````"
+ }
+ 8usize => {
+ "# Mobile App\n\nBuild a mobile app with Dioxus!\n\nExample: [Todo App](https://github.com/DioxusLabs/example-projects/blob/master/ios_demo)\n\n## Support\n\nMobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with either the platform's WebView or experimentally through [WGPU](https://github.com/DioxusLabs/blitz). WebView doesn't support animations, transparency, and native widgets.\n\nMobile support is currently best suited for CRUD-style apps, ideally for internal teams who need to develop quickly but don't care much about animations or native widgets.\n\nThis guide is primarily targeted at iOS apps, however, you can follow it while using the `android` guide in `cargo-mobile`.\n\n## Getting Set up\n\nGetting set up with mobile can be quite challenging. The tooling here isn't great (yet) and might take some hacking around to get things working. macOS M1 is broadly unexplored and might not work for you.\n\nWe're going to be using `cargo-mobile` to build for mobile. First, install it:\n\n````shell\ncargo install --git https://github.com/BrainiumLLC/cargo-mobile\n````\n\nAnd then initialize your app for the right platform. Use the `winit` template for now. Right now, there's no \"Dioxus\" template in cargo-mobile.\n\n````shell\ncargo mobile init\n````\n\nWe're going to completely clear out the `dependencies` it generates for us, swapping out `winit` with `dioxus-mobile`.\n\n````toml\n\n[package]\nname = \"dioxus-ios-demo\"\nversion = \"0.1.0\"\nauthors = []\nedition = \"2018\"\n\n\n# leave the `lib` declaration\n[lib]\ncrate-type = [\"staticlib\", \"cdylib\", \"rlib\"]\n\n\n# leave the binary it generates for us\n[[bin]]\nname = \"dioxus-ios-demo-desktop\"\npath = \"gen/bin/desktop.rs\"\n\n# clear all the dependencies\n[dependencies]\nmobile-entry-point = \"0.1.0\"\ndioxus = { version = \"*\"}\ndioxus-desktop = { version = \"*\" }\nsimple_logger = \"*\"\n````\n\nEdit your `lib.rs`:\n\n````rust\nuse dioxus::prelude::*;\n\nfn main() {\n dioxus_desktop::launch(app);\n}\n\nfn app(cx: Scope) -> Element {\n cx.render(rsx!{\n div {\n \"hello world!\"\n }\n })\n}\n````"
+ }
+ 10usize => {
+ "# Special Attributes\n\nWhile most attributes are simply passed on to the HTML, some have special behaviors.\n\n## The HTML Escape Hatch\n\nIf 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`.\n\nFor 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](https://dioxuslabs.com):\n\n````rust@dangerous_inner_html.rs\n// this should come from a trusted source\nlet contents = \"live dangerously\";\n\ncx.render(rsx! {\ndiv {\n dangerous_inner_html: \"{contents}\",\n}\n})\n````\n\n > \n > 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)](https://en.wikipedia.org/wiki/Cross-site_scripting) attacks to your users.\n > \n > 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.\n\n## Boolean Attributes\n\nMost 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.\n\nSo this RSX wouldn't actually render the `hidden` attribute:\n\n````rust@boolean_attribute.rs\ncx.render(rsx! {\ndiv {\n hidden: \"false\",\n \"hello\"\n}\n})\n````\n\n````html\nhello
\n````\n\nNot all attributes work like this however. *Only the following attributes* have this behavior:\n\n* `allowfullscreen`\n* `allowpaymentrequest`\n* `async`\n* `autofocus`\n* `autoplay`\n* `checked`\n* `controls`\n* `default`\n* `defer`\n* `disabled`\n* `formnovalidate`\n* `hidden`\n* `ismap`\n* `itemscope`\n* `loop`\n* `multiple`\n* `muted`\n* `nomodule`\n* `novalidate`\n* `open`\n* `playsinline`\n* `readonly`\n* `required`\n* `reversed`\n* `selected`\n* `truespeed`\n\nFor any other attributes, a value of `\"false\"` will be sent directly to the DOM."
+ }
+ 1usize => {
+ "# Getting Started\n\nThis section will help you set up your Dioxus project!\n\n## Prerequisites\n\n### An Editor\n\nDioxus integrates very well with the [Rust-Analyzer LSP plugin](https://rust-analyzer.github.io) which will provide appropriate syntax highlighting, code navigation, folding, and more.\n\n### Rust\n\nHead over to [https://rust-lang.org](http://rust-lang.org) and install the Rust compiler.\n\nWe strongly recommend going through the [official Rust book](https://doc.rust-lang.org/book/ch01-00-getting-started.html) *completely*. However, we hope that a Dioxus app can serve as a great first Rust project. With Dioxus, you'll learn about:\n\n* Error handling\n* Structs, Functions, Enums\n* Closures\n* Macros\n\nWe've put a lot of care into making Dioxus syntax familiar and easy to understand, so you won't need deep knowledge of async, lifetimes, or smart pointers until you start building complex Dioxus apps.\n\n## Setup Guides\n\nDioxus supports multiple platforms. Choose the platform you want to target below to get platform-specific setup instructions:\n\n* [Web](web.md): runs in the browser through WebAssembly\n* [Server Side Rendering](ssr.md): renders to HTML text on the server\n* [Liveview](liveview.md): runs on the server, renders in the browser using WebSockets\n* [Desktop](desktop.md): runs in a web view on desktop\n* [Mobile](mobile.md): runs in a web view on mobile\n* [Terminal UI](tui.md): renders text-based graphics in the terminal"
+ }
+ 18usize => {
+ "# Sharing State\n\nOften, multiple components need to access the same state. Depending on your needs, there are several ways to implement this.\n\n## Lifting State\n\nOne approach to share state between components is to \"lift\" it up to the nearest common ancestor. This means putting the `use_state` hook in a parent component, and passing the needed values down as props.\n\nSuppose we want to build a meme editor. We want to have an input to edit the meme caption, but also a preview of the meme with the caption. Logically, the meme and the input are 2 separate components, but they need access to the same state (the current caption).\n\n > \n > Of course, in this simple example, we could write everything in one component – but it is better to split everything out in smaller components to make the code more reusable, maintainable, and performant (this is even more important for larger, complex apps).\n\nWe start with a `Meme` component, responsible for rendering a meme with a given caption:\n\n````rust@meme_editor.rs\n#[inline_props]\nfn Meme<'a>(cx: Scope<'a>, caption: &'a str) -> Element<'a> {\n let container_style = r#\"\n position: relative;\n width: fit-content;\n \"#;\n\n let caption_container_style = r#\"\n position: absolute;\n bottom: 0;\n left: 0;\n right: 0;\n padding: 16px 8px;\n \"#;\n\n let caption_style = r\"\n font-size: 32px;\n margin: 0;\n color: white;\n text-align: center;\n \";\n\n cx.render(rsx!(\n div {\n style: \"{container_style}\",\n img {\n src: \"https://i.imgflip.com/2zh47r.jpg\",\n height: \"500px\",\n },\n div {\n style: \"{caption_container_style}\",\n p {\n style: \"{caption_style}\",\n \"{caption}\"\n }\n }\n }\n ))\n}\n````\n\n > \n > Note that the `Meme` component is unaware where the caption is coming from – it could be stored in `use_state`, `use_ref`, or a constant. This ensures that it is very reusable – the same component can be used for a meme gallery without any changes!\n\nWe also create a caption editor, completely decoupled from the meme. The caption editor must not store the caption itself – otherwise, how will we provide it to the `Meme` component? Instead, it should accept the current caption as a prop, as well as an event handler to delegate input events to:\n\n````rust@meme_editor.rs\n#[inline_props]\nfn CaptionEditor<'a>(\n cx: Scope<'a>,\n caption: &'a str,\n on_input: EventHandler<'a, FormEvent>,\n) -> Element<'a> {\n let input_style = r\"\n border: none;\n background: cornflowerblue;\n padding: 8px 16px;\n margin: 0;\n border-radius: 4px;\n color: white;\n \";\n\n cx.render(rsx!(input {\n style: \"{input_style}\",\n value: \"{caption}\",\n oninput: move |event| on_input.call(event),\n }))\n}\n````\n\nFinally, a third component will render the other two as children. It will be responsible for keeping the state and passing down the relevant props.\n\n````rust@meme_editor.rs\nfn MemeEditor(cx: Scope) -> Element {\n let container_style = r\"\n display: flex;\n flex-direction: column;\n gap: 16px;\n margin: 0 auto;\n width: fit-content;\n \";\n\n let caption = use_state(cx, || \"me waiting for my rust code to compile\".to_string());\n\n cx.render(rsx! {\n div {\n style: \"{container_style}\",\n h1 { \"Meme Editor\" },\n Meme {\n caption: caption,\n },\n CaptionEditor {\n caption: caption,\n on_input: move |event: FormEvent| {caption.set(event.value.clone());},\n },\n }\n })\n}\n````\n\n\n\n## Using Context\n\nSometimes, some state needs to be shared between multiple components far down the tree, and passing it down through props is very inconvenient.\n\nSuppose now that we want to implement a dark mode toggle for our app. To achieve this, we will make every component select styling depending on whether dark mode is enabled or not.\n\n > \n > Note: we're choosing this approach for the sake of an example. There are better ways to implement dark mode (e.g. using CSS variables). Let's pretend CSS variables don't exist – welcome to 2013!\n\nNow, we could write another `use_state` in the top component, and pass `is_dark_mode` down to every component through props. But think about what will happen as the app grows in complexity – almost every component that renders any CSS is going to need to know if dark mode is enabled or not – so they'll all need the same dark mode prop. And every parent component will need to pass it down to them. Imagine how messy and verbose that would get, especially if we had components several levels deep!\n\nDioxus offers a better solution than this \"prop drilling\" – providing context. The [`use_context_provider`](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_context_provider.html) hook is similar to `use_ref`, but it makes it available through [`use_context`](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_context.html) for all children components.\n\nFirst, we have to create a struct for our dark mode configuration:\n\n````rust@meme_editor_dark_mode.rs\nstruct DarkMode(bool);\n````\n\nNow, in a top-level component (like `App`), we can provide the `DarkMode` context to all children components:\n\n````rust@meme_editor_dark_mode.rs\nuse_shared_state_provider(cx, || DarkMode(false));\n````\n\nAs a result, any child component of `App` (direct or not), can access the `DarkMode` context.\n\n````rust@meme_editor_dark_mode.rs\nlet dark_mode_context = use_shared_state::\nfn app(cx: Scope) -> Element {{\n let mut count = use_state(cx, || 0);\n\n cx.render(rsx!(\n h1 {{ "High-Five counter: {{count}}" }}\n button {{ onclick: move |_| count += 1, "Up high!" }}\n button {{ onclick: move |_| count -= 1, "Down low!" }}\n ))\n}}\n", + } + p { + "Dioxus is heavily inspired by React. If you know React, getting started with Dioxus will be a breeze." + } + blockquote { + p { + "This guide assumes you already know some " + Link { to: "https://www.rust-lang.org/", "Rust" } + "! If not, we recommend reading " + Link { to: "https://doc.rust-lang.org/book/ch01-00-getting-started.html", + em { "the book" } + } + " to learn Rust first." + } + } + h2 { id: "features", + Link { + to: BookRoute::Index { + section: IndexSection::Features, + }, + class: "header", + "Features" + } + } + ul { + li { "Desktop apps running natively (no Electron!) in less than 10 lines of code." } + li { "Incredibly ergonomic and powerful state management." } + li { + "Comprehensive inline documentation – hover and guides for all HTML elements, listeners, and events." + } + li { "Extremely memory efficient – 0 global allocations for steady-state components." } + li { "Multi-channel asynchronous scheduler for first-class async support." } + li { + "And more! Read the " + Link { to: "https://dioxuslabs.com/blog/introducing-dioxus/", "full release post" } + "." + } + } + h3 { id: "multiplatform", + Link { + to: BookRoute::Index { + section: IndexSection::Multiplatform, + }, + class: "header", + "Multiplatform" + } + } + p { + "Dioxus is a " + em { "portable" } + " toolkit, meaning the Core implementation can run anywhere with no platform-dependent linking. Unlike many other Rust frontend toolkits, Dioxus is not intrinsically linked to WebSys. In fact, every element and event listener can be swapped out at compile time. By default, Dioxus ships with the " + code { "html" } + " feature enabled, but this can be disabled depending on your target renderer." + } + p { "Right now, we have several 1st-party renderers:" } + ul { + li { "WebSys (for WASM): Great support" } + li { "Tao/Tokio (for Desktop apps): Good support" } + li { "Tao/Tokio (for Mobile apps): Poor support" } + li { "SSR (for generating static markup)" } + li { "TUI/Rink (for terminal-based apps): Experimental" } + } + h2 { id: "stability", + Link { + to: BookRoute::Index { + section: IndexSection::Stability, + }, + class: "header", + "Stability" + } + } + p { "Dioxus has not reached a stable release yet." } + p { + "Web: Since the web is a fairly mature platform, we expect there to be very little API churn for web-based features." + } + p { + "Desktop: APIs will likely be in flux as we figure out better patterns than our ElectronJS counterpart." + } + p { "SSR: We don't expect the SSR API to change drastically in the future." } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum GettingStartedIndexSection { + #[default] + Empty, + GettingStarted, + Prerequisites, + AnEditor, + Rust, + SetupGuides, +} +impl std::str::FromStr for GettingStartedIndexSection { + type Err = GettingStartedIndexSectionParseError; + fn from_str(s: &str) -> Result
\nsudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev libappindicator3-dev\n" } + p { + "When using Debian/bullseye " + code { "libappindicator3-dev" } + " is no longer available but replaced by " + code { "libayatana-appindicator3-dev" } + "." + } + CodeBlock { contents: "
\n# on Debian/bullseye use:\nsudo apt install libwebkit2gtk-4.0-dev libgtk-3-dev libayatana-appindicator3-dev\n" } + p { + "If you run into issues, make sure you have all the basics installed, as outlined in the " + Link { to: "https://tauri.studio/v1/guides/getting-started/prerequisites#setting-up-linux", + "Tauri docs" + } + "." + } + h3 { id: "macos", + Link { + to: BookRoute::GettingStartedDesktop { + section: GettingStartedDesktopSection::Macos, + }, + class: "header", + "MacOS" + } + } + p { + "Currently – everything for macOS is built right in! However, you might run into an issue if you're using nightly Rust due to some permissions issues in our Tao dependency (which have been resolved but not published)." + } + h2 { id: "creating-a-project", + Link { + to: BookRoute::GettingStartedDesktop { + section: GettingStartedDesktopSection::CreatingAProject, + }, + class: "header", + "Creating a Project" + } + } + p { "Create a new crate:" } + CodeBlock { contents: "
\ncargo new --bin demo\ncd demo\n" } + p { + "Add Dioxus and the desktop renderer as dependencies (this will edit your " + code { "Cargo.toml" } + "):" + } + CodeBlock { contents: "
\ncargo add dioxus\ncargo add dioxus-desktop\n" } + p { + "Edit your " + code { "main.rs" } + ":" + } + CodeBlock { + contents: "
\n#![allow(non_snake_case)]\n// import the prelude to get access to the `rsx!` macro and the `Scope` and `Element` types\nuse dioxus::prelude::*;\n\nfn main() {{\n // launch the dioxus app in a webview\n dioxus_desktop::launch(App);\n}}\n\n// define a component that renders a div with the text "Hello, world!"\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n div {{\n "Hello, world!"\n }}\n }})\n}}\n", + name: "hello_world_desktop.rs".to_string(), + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum GettingStartedWebSection { + #[default] + Empty, + Web, + Support, + Tooling, + CreatingAProject, +} +impl std::str::FromStr for GettingStartedWebSection { + type Err = GettingStartedWebSectionParseError; + fn from_str(s: &str) -> Result
\ncargo install dioxus-cli\n" } + p { + "Make sure the " + code { "wasm32-unknown-unknown" } + " target for rust is installed:" + } + CodeBlock { contents: "
\nrustup target add wasm32-unknown-unknown\n" } + h2 { id: "creating-a-project", + Link { + to: BookRoute::GettingStartedWeb { + section: GettingStartedWebSection::CreatingAProject, + }, + class: "header", + "Creating a Project" + } + } + p { "Create a new crate:" } + CodeBlock { contents: "
\ncargo new --bin demo\ncd demo\n" } + p { + "Add Dioxus and the web renderer as dependencies (this will edit your " + code { "Cargo.toml" } + "):" + } + CodeBlock { contents: "
\ncargo add dioxus\ncargo add dioxus-web\n" } + p { + "Edit your " + code { "main.rs" } + ":" + } + CodeBlock { + contents: "
\n#![allow(non_snake_case)]\n// import the prelude to get access to the `rsx!` macro and the `Scope` and `Element` types\nuse dioxus::prelude::*;\n\nfn main() {{\n // launch the web app\n dioxus_web::launch(App);\n}}\n\n// create a component that renders a div with the text "Hello, world!"\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n div {{\n "Hello, world!"\n }}\n }})\n}}\n", + name: "hello_world_web.rs".to_string(), + } + p { "And to serve our app:" } + CodeBlock { contents: "
\ndioxus serve\n" }
+ }
+}
+#[derive(
+ Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize,
+)]
+pub enum GettingStartedHotReloadSection {
+ #[default]
+ Empty,
+ SettingUpHotReload,
+ Setup,
+ Usage,
+ Limitations,
+}
+impl std::str::FromStr for GettingStartedHotReloadSection {
+ type Err = GettingStartedHotReloadSectionParseError;
+ fn from_str(s: &str) -> Result\ndioxus serve --hot-reload\n" } + ol { + li { "change some code within a rsx macro" } + li { "open your localhost in a browser" } + li { "save and watch the style change without recompiling" } + } + h1 { id: "limitations", + Link { + to: BookRoute::GettingStartedHotReload { + section: GettingStartedHotReloadSection::Limitations, + }, + class: "header", + "Limitations" + } + } + ol { + li { + "The interpreter can only use expressions that existed on the last full recompile. If you introduce a new variable or expression to the rsx call, it will trigger a full recompile to capture the expression." + } + li { + "Components and Iterators can contain arbitrary rust code and will trigger a full recompile when changed." + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum GettingStartedSsrSection { + #[default] + Empty, + ServerSideRendering, + MultithreadedSupport, + Setup, +} +impl std::str::FromStr for GettingStartedSsrSection { + type Err = GettingStartedSsrSectionParseError; + fn from_str(s: &str) -> Result
\ncargo new --bin demo\ncd app\n" } + p { "Add Dioxus and the ssr renderer as dependencies:" } + CodeBlock { contents: "
\ncargo add dioxus\ncargo add dioxus-ssr\n" } + p { + "Next, add all the Axum dependencies. This will be different if you're using a different Web Framework" + } + CodeBlock { contents: "
\ncargo add tokio --features full\ncargo add axum\n" } + p { "Your dependencies should look roughly like this:" } + CodeBlock { + contents: "
\n[dependencies]\naxum = "0.4.5"\ndioxus = {{ version = "*" }}\ndioxus-ssr = {{ version = "*" }}\ntokio = {{ version = "1.15.0", features = ["full"] }}\n", + } + p { "Now, set up your Axum app to respond on an endpoint." } + CodeBlock { + contents: "
\nuse axum::{{response::Html, routing::get, Router}};\nuse dioxus::prelude::*;\n\n#[tokio::main]\nasync fn main() {{\n let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 3000));\n println!("listening on http://{{}}", addr);\n\n axum::Server::bind(&addr)\n .serve(\n Router::new()\n .route("/", get(app_endpoint))\n .into_make_service(),\n )\n .await\n .unwrap();\n}}\n", + } + p { + "And then add our endpoint. We can either render " + code { "rsx!" } + " directly:" + } + CodeBlock { contents: "
\nasync fn app_endpoint() -> Html<String> {{\n // render the rsx! macro to HTML\n Html(dioxus_ssr::render_lazy(rsx! {{\n div {{ "hello world!" }}\n }}))\n}}\n" } + p { "Or we can render VirtualDoms." } + CodeBlock { + contents: "
\nasync fn app_endpoint() -> Html<String> {{\n // create a component that renders a div with the text "hello world"\n fn app(cx: Scope) -> Element {{\n cx.render(rsx!(div {{ "hello world" }}))\n }}\n // create a VirtualDom with the app component\n let mut app = VirtualDom::new(app);\n // rebuild the VirtualDom before rendering\n let _ = app.rebuild();\n\n // render the VirtualDom to HTML\n Html(dioxus_ssr::render_vdom(&app))\n}}\n", + } + p { "And that's it!" } + blockquote { + p { + "You might notice that you cannot hold the VirtualDom across an await point. Dioxus is currently not ThreadSafe, so it " + em { "must" } + " remain on the thread it started. We are working on loosening this requirement." + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum GettingStartedLiveviewSection { + #[default] + Empty, + Liveview, + Support, + Setup, +} +impl std::str::FromStr for GettingStartedLiveviewSection { + type Err = GettingStartedLiveviewSectionParseError; + fn from_str(s: &str) -> Result
\ncargo new --bin demo\ncd app\n" } + p { "Add Dioxus and the liveview renderer with the Axum feature as dependencies:" } + CodeBlock { contents: "
\ncargo add dioxus\ncargo add dioxus-liveview --features axum\n" } + p { + "Next, add all the Axum dependencies. This will be different if you're using a different Web Framework" + } + CodeBlock { contents: "
\ncargo add tokio --features full\ncargo add axum\n" } + p { "Your dependencies should look roughly like this:" } + CodeBlock { + contents: "
\n[dependencies]\naxum = "0.4.5"\ndioxus = {{ version = "*" }}\ndioxus-liveview = {{ version = "*", features = ["axum"] }}\ntokio = {{ version = "1.15.0", features = ["full"] }}\n", + } + p { "Now, set up your Axum app to respond on an endpoint." } + CodeBlock { + contents: "
\n#[tokio::main]\nasync fn main() {{\n let addr: std::net::SocketAddr = ([127, 0, 0, 1], 3030).into();\n\n let view = dioxus_liveview::LiveViewPool::new();\n\n let app = Router::new()\n // The root route contains the glue code to connect to the WebSocket\n .route(\n "/",\n get(move || async move {{\n Html(format!(\n r#"\n <!DOCTYPE html>\n <html>\n <head> <title>Dioxus LiveView with Axum</title> </head>\n <body> <div id="main"></div> </body>\n {{glue}}\n </html>\n "#,\n // Create the glue code to connect to the WebSocket on the "/ws" route\n glue = dioxus_liveview::interpreter_glue(&format!("ws://{{addr}}/ws"))\n ))\n }}),\n )\n // The WebSocket route is what Dioxus uses to communicate with the browser\n .route(\n "/ws",\n get(move |ws: WebSocketUpgrade| async move {{\n ws.on_upgrade(move |socket| async move {{\n // When the WebSocket is upgraded, launch the LiveView with the app component\n _ = view.launch(dioxus_liveview::axum_socket(socket), app).await;\n }})\n }}),\n );\n\n println!("Listening on http://{{}}", addr);\n\n axum::Server::bind(&addr.to_string().parse().unwrap())\n .serve(app.into_make_service())\n .await\n .unwrap();\n}}\n", + name: "hello_world_liveview.rs".to_string(), + } + p { "And then add our app component:" } + CodeBlock { + contents: "
\nfn app(cx: Scope) -> Element {{\n cx.render(rsx! {{\n div {{\n "Hello, world!"\n }}\n }})\n}}\n", + name: "hello_world_liveview.rs".to_string(), + } + p { "And that's it!" } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum GettingStartedTuiSection { + #[default] + Empty, + TerminalUi, + Support, + GettingSetUp, +} +impl std::str::FromStr for GettingStartedTuiSection { + type Err = GettingStartedTuiSectionParseError; + fn from_str(s: &str) -> Result
\ncargo new --bin demo\ncd demo\ncargo add dioxus\ncargo add dioxus-tui\n" } + p { + "Then, edit your " + code { "main.rs" } + " with the basic template." + } + CodeBlock { + contents: "
\n#![allow(non_snake_case)]\n// import the prelude to get access to the `rsx!` macro and the `Scope` and `Element` types\nuse dioxus::prelude::*;\n\nfn main() {{\n // launch the app in the terminal\n dioxus_tui::launch(App);\n}}\n\n// create a component that renders a div with the text "Hello, world!"\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n div {{\n "Hello, world!"\n }}\n }})\n}}\n", + name: "hello_world_tui.rs".to_string(), + } + p { "To run our app:" } + CodeBlock { contents: "
\ncargo run\n" }
+ p {
+ "Press \"ctrl-c\" to close the app. To switch from \"ctrl-c\" to just \"q\" to quit you can launch the app with a configuration to disable the default quit and use the root TuiContext to quit on your own."
+ }
+ CodeBlock {
+ contents: "\n// todo remove deprecated\n#![allow(non_snake_case, deprecated)]\n\nuse dioxus::events::{{KeyCode, KeyboardEvent}};\nuse dioxus::prelude::*;\nuse dioxus_tui::TuiContext;\n\nfn main() {{\n dioxus_tui::launch_cfg(\n App,\n dioxus_tui::Config::new()\n .without_ctrl_c_quit()\n // Some older terminals only support 16 colors or ANSI colors\n // If your terminal is one of these, change this to BaseColors or ANSI\n .with_rendering_mode(dioxus_tui::RenderingMode::Rgb),\n );\n}}\n\nfn App(cx: Scope) -> Element {{\n let tui_ctx: TuiContext = cx.consume_context().unwrap();\n\n cx.render(rsx! {{\n div {{\n width: "100%",\n height: "10px",\n background_color: "red",\n justify_content: "center",\n align_items: "center",\n onkeydown: move |k: KeyboardEvent| if let KeyCode::Q = k.key_code {{\n tui_ctx.quit();\n }},\n\n "Hello world!"\n }}\n }})\n}}\n", + name: "hello_world_tui_no_ctrl_c.rs".to_string(), + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum GettingStartedMobileSection { + #[default] + Empty, + MobileApp, + Support, + GettingSetUp, +} +impl std::str::FromStr for GettingStartedMobileSection { + type Err = GettingStartedMobileSectionParseError; + fn from_str(s: &str) -> Result
\ncargo install --git https://github.com/BrainiumLLC/cargo-mobile\n" } + p { + "And then initialize your app for the right platform. Use the " + code { "winit" } + " template for now. Right now, there's no \"Dioxus\" template in cargo-mobile." + } + CodeBlock { contents: "
\ncargo mobile init\n" }
+ p {
+ "We're going to completely clear out the "
+ code { "dependencies" }
+ " it generates for us, swapping out "
+ code { "winit" }
+ " with "
+ code { "dioxus-mobile" }
+ "."
+ }
+ CodeBlock {
+ contents: "\n\n[package]\nname = "dioxus-ios-demo"\nversion = "0.1.0"\nauthors = []\nedition = "2018"\n\n\n# leave the `lib` declaration\n[lib]\ncrate-type = ["staticlib", "cdylib", "rlib"]\n\n\n# leave the binary it generates for us\n[[bin]]\nname = "dioxus-ios-demo-desktop"\npath = "gen/bin/desktop.rs"\n\n# clear all the dependencies\n[dependencies]\nmobile-entry-point = "0.1.0"\ndioxus = {{ version = "*"}}\ndioxus-desktop = {{ version = "*" }}\nsimple_logger = "*"\n", + } + p { + "Edit your " + code { "lib.rs" } + ":" + } + CodeBlock { + contents: "
\nuse dioxus::prelude::*;\n\nfn main() {{\n dioxus_desktop::launch(app);\n}}\n\nfn app(cx: Scope) -> Element {{\n cx.render(rsx!{{\n div {{\n "hello world!"\n }}\n }})\n}}\n", + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum DescribingUiIndexSection { + #[default] + Empty, + DescribingTheUi, + RsxFeatures, + Attributes, + CustomAttributes, + Interpolation, + Children, + Fragments, + Expressions, + Loops, + IfStatements, +} +impl std::str::FromStr for DescribingUiIndexSection { + type Err = DescribingUiIndexSectionParseError; + fn from_str(s: &str) -> Result
\n// define a component that renders a div with the text "Hello, world!"\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n div {{\n "Hello, world!"\n }}\n }})\n}}\n", + name: "hello_world_desktop.rs".to_string(), + } + p { + "Here, we use the " + code { "rsx!" } + " macro to " + em { "declare" } + " that we want a " + code { "div" } + " element, containing the text " + code { "\"Hello, world!\"" } + ". Dioxus takes the RSX and constructs a UI from it." + } + h2 { id: "rsx-features", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::RsxFeatures, + }, + class: "header", + "RSX Features" + } + } + p { + "RSX is very similar to HTML in that it describes elements with attributes and children. Here's an empty " + code { "div" } + " element in RSX, as well as the resulting HTML:" + } + CodeBlock { + contents: "
\ncx.render(rsx!(div {{\n// attributes / listeners\n// children\n}}))\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { contents: "
\n<div></div>\n" } + h3 { id: "attributes", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::Attributes, + }, + class: "header", + "Attributes" + } + } + p { + "Attributes (and " + Link { + to: BookRoute::InteractivityIndex { + section: InteractivityIndexSection::Empty, + }, + "listeners" + } + ") modify the behavior or appearance of the element they are attached to. They are specified inside the " + code { "{{}}" } + " brackets, using the " + code { "name: value" } + " syntax. You can provide the value as a literal in the RSX:" + } + CodeBlock { + contents: "
\ncx.render(rsx!(a {{\nhref: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",\nclass: "primary_button",\ncolor: "red",\n}}))\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { contents: "
\n<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" class="primary_button" autofocus="true" style="color: red"></a>\n" } + blockquote { + p { + "Note: All attributes defined in " + code { "dioxus-html" } + " follow the snake_case naming convention. They transform their " + code { "snake_case" } + " names to HTML's " + code { "camelCase" } + " attributes." + } + } + blockquote { + p { + "Note: Styles can be used directly outside of the " + code { "style:" } + " attribute. In the above example, " + code { "color: \"red\"" } + " is turned into " + code { "style=\"color: red\"" } + "." + } + } + h4 { id: "custom-attributes", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::CustomAttributes, + }, + class: "header", + "Custom Attributes" + } + } + p { + "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:" + } + CodeBlock { + contents: "
\ncx.render(rsx!(b {{\n "customAttribute": "value",\n}}))\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { contents: "
\n<b customAttribute="value">\n</b>\n" } + h3 { id: "interpolation", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::Interpolation, + }, + class: "header", + "Interpolation" + } + } + p { + "Similarly to how you can " + Link { to: "https://doc.rust-lang.org/rust-by-example/hello/print/fmt.html", + "format" + } + " Rust strings, you can also interpolate in RSX text. Use " + code { "{{variable}}" } + " to Display the value of a variable in a string, or " + code { "{{variable:?}}" } + " to use the Debug representation:" + } + CodeBlock { + contents: "
\nlet coordinates = (42, 0);\nlet country = "es";\ncx.render(rsx!(div {{\nclass: "country-{{country}}",\n"position": "{{coordinates:?}}",\n// arbitrary expressions are allowed,\n// as long as they don't contain `{{}}`\ndiv {{\n "{{country.to_uppercase()}}"\n}},\ndiv {{\n "{{7*6}}"\n}},\n// {{}} can be escaped with {{{{}}}}\ndiv {{\n "{{{{}}}}"\n}},\n}}))\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { + contents: "
\n<div class="country-es" position="(42, 0)">\n <div>ES</div>\n <div>42</div>\n <div>{{}}</div>\n</div>\n", + } + h3 { id: "children", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::Children, + }, + class: "header", + "Children" + } + } + p { + "To add children to an element, put them inside the " + code { "{{}}" } + " brackets after all attributes and listeners in the element. They can be other elements, text, or " + Link { + to: BookRoute::DescribingUiComponents { + section: DescribingUiComponentsSection::Empty, + }, + "components" + } + ". For example, you could have an " + code { "ol" } + " (ordered list) element, containing 3 " + code { "li" } + " (list item) elements, each of which contains some text:" + } + CodeBlock { + contents: "
\ncx.render(rsx!(ol {{\nli {{"First Item"}}\nli {{"Second Item"}}\nli {{"Third Item"}}\n}}))\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { + contents: "
\n<ol>\n <li>First Item</li>\n <li>Second Item</li>\n <li>Third Item</li>\n</ol>\n", + } + h3 { id: "fragments", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::Fragments, + }, + class: "header", + "Fragments" + } + } + p { + "You can render multiple elements at the top level of " + code { "rsx!" } + " and they will be automatically grouped." + } + CodeBlock { + contents: "
\ncx.render(rsx!(\np {{"First Item"}},\np {{"Second Item"}},\n))\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { contents: "
\n<p>First Item</p>\n<p>Second Item</p>\n" } + h3 { id: "expressions", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::Expressions, + }, + class: "header", + "Expressions" + } + } + p { + "You can include arbitrary Rust expressions as children within RSX that implements " + Link { to: "https://docs.rs/dioxus-core/0.3/dioxus_core/trait.IntoDynNode.html", + "IntoDynNode" + } + ". This is useful for displaying data from an " + Link { to: "https://doc.rust-lang.org/stable/book/ch13-02-iterators.html#processing-a-series-of-items-with-iterators", + "iterator" + } + ":" + } + CodeBlock { + contents: "
\nlet text = "Dioxus";\ncx.render(rsx!(span {{\ntext.to_uppercase(),\n// create a list of text from 0 to 9\n(0..10).map(|i| rsx!{{ i.to_string() }})\n}}))\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { contents: "
\n<span>DIOXUS0123456789</span>\n" } + h3 { id: "loops", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::Loops, + }, + class: "header", + "Loops" + } + } + p { "In addition to iterators you can also use for loops directly within RSX:" } + CodeBlock { + contents: "
\ncx.render(rsx!{{\n// use a for loop where the body itself is RSX\ndiv {{\n // create a list of text from 0 to 9\n for i in 0..3 {{\n // NOTE: the body of the loop is RSX not a rust statement\n div {{\n "{{i}}"\n }}\n }}\n}}\n// iterator equivalent\ndiv {{\n (0..3).map(|i| rsx!{{ div {{ "{{i}}" }} }})\n}}\n}})\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { + contents: "
\n<div>0</div>\n<div>1</div>\n<div>2</div>\n<div>0</div>\n<div>1</div>\n<div>2</div>\n", + } + h3 { id: "if-statements", + Link { + to: BookRoute::DescribingUiIndex { + section: DescribingUiIndexSection::IfStatements, + }, + class: "header", + "If statements" + } + } + p { "You can also use if statements without an else branch within RSX:" } + CodeBlock { + contents: "
\ncx.render(rsx!{{\n// use if statements without an else\nif true {{\n rsx!(div {{ "true" }})\n}}\n}})\n", + name: "rsx_overview.rs".to_string(), + } + CodeBlock { contents: "
\n<div>true</div>\n" } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum DescribingUiSpecialAttributesSection { + #[default] + Empty, + SpecialAttributes, + TheHtmlEscapeHatch, + BooleanAttributes, +} +impl std::str::FromStr for DescribingUiSpecialAttributesSection { + type Err = DescribingUiSpecialAttributesSectionParseError; + fn from_str(s: &str) -> Result
\n// this should come from a trusted source\nlet contents = "live <b>dangerously</b>";\n\ncx.render(rsx! {{\ndiv {{\n dangerous_inner_html: "{{contents}}",\n}}\n}})\n", + name: "dangerous_inner_html.rs".to_string(), + } + blockquote { + p { + "Note! This attribute is called \"dangerous_inner_html\" because it is " + strong { "dangerous" } + " to pass it data you don't trust. If you're not careful, you can easily expose " + Link { to: "https://en.wikipedia.org/wiki/Cross-site_scripting", + "cross-site scripting (XSS)" + } + " attacks to your users." + } + p { + "If you're handling untrusted input, make sure to sanitize your HTML before passing it into " + code { "dangerous_inner_html" } + " – or just pass it to a Text Element to escape any HTML tags." + } + } + h2 { id: "boolean-attributes", + Link { + to: BookRoute::DescribingUiSpecialAttributes { + section: DescribingUiSpecialAttributesSection::BooleanAttributes, + }, + class: "header", + "Boolean Attributes" + } + } + p { + "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 " + code { "\"false\"" } + " will cause them to be removed from the target element." + } + p { + "So this RSX wouldn't actually render the " + code { "hidden" } + " attribute:" + } + CodeBlock { + contents: "
\ncx.render(rsx! {{\ndiv {{\n hidden: "false",\n "hello"\n}}\n}})\n", + name: "boolean_attribute.rs".to_string(), + } + CodeBlock { contents: "
\n<div>hello</div>\n" } + p { + "Not all attributes work like this however. " + em { "Only the following attributes" } + " have this behavior:" + } + ul { + li { + code { "allowfullscreen" } + } + li { + code { "allowpaymentrequest" } + } + li { + code { "async" } + } + li { + code { "autofocus" } + } + li { + code { "autoplay" } + } + li { + code { "checked" } + } + li { + code { "controls" } + } + li { + code { "default" } + } + li { + code { "defer" } + } + li { + code { "disabled" } + } + li { + code { "formnovalidate" } + } + li { + code { "hidden" } + } + li { + code { "ismap" } + } + li { + code { "itemscope" } + } + li { + code { "loop" } + } + li { + code { "multiple" } + } + li { + code { "muted" } + } + li { + code { "nomodule" } + } + li { + code { "novalidate" } + } + li { + code { "open" } + } + li { + code { "playsinline" } + } + li { + code { "readonly" } + } + li { + code { "required" } + } + li { + code { "reversed" } + } + li { + code { "selected" } + } + li { + code { "truespeed" } + } + } + p { + "For any other attributes, a value of " + code { "\"false\"" } + " will be sent directly to the DOM." + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum DescribingUiComponentsSection { + #[default] + Empty, + Components, +} +impl std::str::FromStr for DescribingUiComponentsSection { + type Err = DescribingUiComponentsSectionParseError; + fn from_str(s: &str) -> Result
\n// define a component that renders a div with the text "Hello, world!"\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n div {{\n "Hello, world!"\n }}\n }})\n}}\n", + name: "hello_world_desktop.rs".to_string(), + } + blockquote { + p { + "You'll probably want to add " + code { "#![allow(non_snake_case)]" } + " to the top of your crate to avoid warnings about UpperCamelCase component names" + } + } + p { + "A Component is responsible for some rendering task – typically, rendering an isolated part of the user interface. For example, you could have an " + code { "About" } + " component that renders a short description of Dioxus Labs:" + } + CodeBlock { + contents: "
\npub fn About(cx: Scope) -> Element {{\n cx.render(rsx!(p {{\n b {{"Dioxus Labs"}}\n " An Open Source project dedicated to making Rust UI wonderful."\n }}))\n}}\n", + name: "components.rs".to_string(), + } + p { + "Then, you can render your component in another component, similarly to how elements are rendered:" + } + CodeBlock { + contents: "
\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n About {{}},\n About {{}},\n }})\n}}\n", + name: "components.rs".to_string(), + } + p { + img { + src: asset!( + "/assets/blog/release-03/screenshot_about_component.png", + ImageAssetOptions::new().with_webp() + ), + alt: "Screenshot containing the About component twice", + title: "", + } + } + blockquote { + p { + "At this point, it might seem like components are nothing more than functions. However, as you learn more about the features of Dioxus, you'll see that they are actually more powerful!" + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum DescribingUiComponentPropsSection { + #[default] + Empty, + ComponentProps, + Deriveprops, + OwnedProps, + BorrowedProps, + PropOptions, + OptionalProps, + ExplicitlyRequiredOptionS, + DefaultProps, + AutomaticConversionWithInto, + TheInlinePropsMacro, +} +impl std::str::FromStr for DescribingUiComponentPropsSection { + type Err = DescribingUiComponentPropsSectionParseError; + fn from_str(s: &str) -> Result
\n// Remember: Owned props must implement `PartialEq`!\n#[derive(PartialEq, Props)]\nstruct LikesProps {{\n score: i32,\n}}\n\nfn Likes(cx: Scope<LikesProps>) -> Element {{\n cx.render(rsx! {{\n div {{\n "This post has ",\n b {{ "{{cx.props.score}}" }},\n " likes"\n }}\n }})\n}}\n", + name: "component_owned_props.rs".to_string(), + } + p { + "You can then pass prop values to the component the same way you would pass attributes to an element:" + } + CodeBlock { + contents: "
\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n Likes {{\n score: 42,\n }},\n }})\n}}\n", + name: "component_owned_props.rs".to_string(), + } + p { + img { + src: asset!( + "/assets/blog/release-03/component_owned_props_screenshot.png", + ImageAssetOptions::new().with_webp() + ), + alt: "Screenshot: Likes component", + title: "", + } + } + h3 { id: "borrowed-props", + Link { + to: BookRoute::DescribingUiComponentProps { + section: DescribingUiComponentPropsSection::BorrowedProps, + }, + class: "header", + "Borrowed Props" + } + } + p { + "Owned props work well if your props are easy to copy around – like a single number. But what if we need to pass a larger data type, like a String from an " + code { "App" } + " Component to a " + code { "TitleCard" } + " subcomponent? A naive solution might be to " + Link { to: "https://doc.rust-lang.org/std/clone/trait.Clone.html", + code { ".clone()" } + } + " the String, creating a copy of it for the subcomponent – but this would be inefficient, especially for larger Strings." + } + p { + "Rust allows for something more efficient – borrowing the String as a " + code { "&str" } + " – this is what Borrowed Props are for!" + } + CodeBlock { + contents: "
\n#[derive(Props)]\nstruct TitleCardProps<'a> {{\n title: &'a str,\n}}\n\nfn TitleCard<'a>(cx: Scope<'a, TitleCardProps<'a>>) -> Element {{\n cx.render(rsx! {{\n h1 {{ "{{cx.props.title}}" }}\n }})\n}}\n", + name: "component_borrowed_props.rs".to_string(), + } + p { "We can then use the component like this:" } + CodeBlock { + contents: "
\nfn App(cx: Scope) -> Element {{\n let hello = "Hello Dioxus!";\n\n cx.render(rsx!(TitleCard {{ title: hello }}))\n}}\n", + name: "component_borrowed_props.rs".to_string(), + } + p { + img { + src: asset!( + "/assets/blog/release-03/component_borrowed_props_screenshot.png", + ImageAssetOptions::new().with_webp() + ), + alt: "Screenshot: TitleCard component", + title: "", + } + } + p { + "Borrowed props can be very useful, but they do not allow for memorization so they will " + em { "always" } + " rerun when the parent scope is rerendered. Because of this Borrowed Props should be reserved for components that are cheap to rerun or places where cloning data is an issue. Using Borrowed Props everywhere will result in large parts of your app rerunning every interaction." + } + h2 { id: "prop-options", + Link { + to: BookRoute::DescribingUiComponentProps { + section: DescribingUiComponentPropsSection::PropOptions, + }, + class: "header", + "Prop Options" + } + } + p { + "The " + code { "#[derive(Props)]" } + " macro has some features that let you customize the behavior of props." + } + h3 { id: "optional-props", + Link { + to: BookRoute::DescribingUiComponentProps { + section: DescribingUiComponentPropsSection::OptionalProps, + }, + class: "header", + "Optional Props" + } + } + p { + "You can create optional fields by using the " + code { "Option<…>" } + " type for a field:" + } + CodeBlock { + contents: "
\n#[derive(Props)]\nstruct OptionalProps<'a> {{\n title: &'a str,\n subtitle: Option<&'a str>,\n}}\n\nfn Title<'a>(cx: Scope<'a, OptionalProps>) -> Element<'a> {{\n cx.render(rsx!(h1{{\n "{{cx.props.title}}: ",\n cx.props.subtitle.unwrap_or("No subtitle provided"),\n }}))\n}}\n", + name: "component_props_options.rs".to_string(), + } + p { "Then, you can choose to either provide them or not:" } + CodeBlock { + contents: "
\nTitle {{\ntitle: "Some Title",\n}},\nTitle {{\ntitle: "Some Title",\nsubtitle: "Some Subtitle",\n}},\n// Providing an Option explicitly won't compile though:\n// Title {{\n// title: "Some Title",\n// subtitle: None,\n// }},\n", + name: "component_props_options.rs".to_string(), + } + h3 { id: "explicitly-required-option-s", + Link { + to: BookRoute::DescribingUiComponentProps { + section: DescribingUiComponentPropsSection::ExplicitlyRequiredOptionS, + }, + class: "header", + "Explicitly Required Option s" + } + } + p { + "If you want to explicitly require an " + code { "Option" } + ", and not an optional prop, you can annotate it with " + code { "#[props(!optional)]" } + ":" + } + CodeBlock { + contents: "
\n#[derive(Props)]\nstruct ExplicitOptionProps<'a> {{\n title: &'a str,\n #[props(!optional)]\n subtitle: Option<&'a str>,\n}}\n\nfn ExplicitOption<'a>(cx: Scope<'a, ExplicitOptionProps>) -> Element<'a> {{\n cx.render(rsx!(h1 {{\n "{{cx.props.title}}: ",\n cx.props.subtitle.unwrap_or("No subtitle provided"),\n }}))\n}}\n", + name: "component_props_options.rs".to_string(), + } + p { + "Then, you have to explicitly pass either " + code { "Some(\"str\")" } + " or " + code { "None" } + ":" + } + CodeBlock { + contents: "
\nExplicitOption {{\ntitle: "Some Title",\nsubtitle: None,\n}},\nExplicitOption {{\ntitle: "Some Title",\nsubtitle: Some("Some Title"),\n}},\n// This won't compile:\n// ExplicitOption {{\n// title: "Some Title",\n// }},\n", + name: "component_props_options.rs".to_string(), + } + h3 { id: "default-props", + Link { + to: BookRoute::DescribingUiComponentProps { + section: DescribingUiComponentPropsSection::DefaultProps, + }, + class: "header", + "Default Props" + } + } + p { + "You can use " + code { "#[props(default = 42)]" } + " to make a field optional and specify its default value:" + } + CodeBlock { + contents: "
\n#[derive(PartialEq, Props)]\nstruct DefaultProps {{\n // default to 42 when not provided\n #[props(default = 42)]\n number: i64,\n}}\n\nfn DefaultComponent(cx: Scope<DefaultProps>) -> Element {{\n cx.render(rsx!(h1 {{ "{{cx.props.number}}" }}))\n}}\n", + name: "component_props_options.rs".to_string(), + } + p { "Then, similarly to optional props, you don't have to provide it:" } + CodeBlock { + contents: "
\nDefaultComponent {{\nnumber: 5,\n}},\nDefaultComponent {{}},\n", + name: "component_props_options.rs".to_string(), + } + h3 { id: "automatic-conversion-with-into", + Link { + to: BookRoute::DescribingUiComponentProps { + section: DescribingUiComponentPropsSection::AutomaticConversionWithInto, + }, + class: "header", + "Automatic Conversion with .into" + } + } + p { + "It is common for Rust functions to accept " + code { "impl Into
\n#[derive(PartialEq, Props)]\nstruct IntoProps {{\n #[props(into)]\n string: String,\n}}\n\nfn IntoComponent(cx: Scope<IntoProps>) -> Element {{\n cx.render(rsx!(h1 {{ "{{cx.props.string}}" }}))\n}}\n", + name: "component_props_options.rs".to_string(), + } + p { "Then, you can use it so:" } + CodeBlock { + contents: "
\nIntoComponent {{\nstring: "some &str",\n}},\n", + name: "component_props_options.rs".to_string(), + } + h2 { id: "the-inline-props-macro", + Link { + to: BookRoute::DescribingUiComponentProps { + section: DescribingUiComponentPropsSection::TheInlinePropsMacro, + }, + class: "header", + "The inline_props macro" + } + } + p { + "So far, every Component function we've seen had a corresponding ComponentProps struct to pass in props. This was quite verbose... Wouldn't it be nice to have props as simple function arguments? Then we wouldn't need to define a Props struct, and instead of typing " + code { "cx.props.whatever" } + ", we could just use " + code { "whatever" } + " directly!" + } + p { + code { "inline_props" } + " allows you to do just that. Instead of typing the \"full\" version:" + } + CodeBlock { + contents: "
\n#[derive(Props, PartialEq)]\nstruct TitleCardProps {{\n title: String,\n}}\n\nfn TitleCard(cx: Scope<TitleCardProps>) -> Element {{\n cx.render(rsx!{{\n h1 {{ "{{cx.props.title}}" }}\n }})\n}}\n", + } + p { + "...you can define a function that accepts props as arguments. Then, just annotate it with " + code { "#[inline_props]" } + ", and the macro will turn it into a regular Component for you:" + } + CodeBlock { contents: "
\n#[inline_props]\nfn TitleCard(cx: Scope, title: String) -> Element {{\n cx.render(rsx!{{\n h1 {{ "{{title}}" }}\n }})\n}}\n" } + blockquote { + p { + "While the new Component is shorter and easier to read, this macro should not be used by library authors since you have less control over Prop documentation." + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum DescribingUiComponentChildrenSection { + #[default] + Empty, + ComponentChildren, + TheChildrenField, +} +impl std::str::FromStr for DescribingUiComponentChildrenSection { + type Err = DescribingUiComponentChildrenSectionParseError; + fn from_str(s: &str) -> Result
\n#[derive(Props)]\nstruct ClickableProps<'a> {{\n href: &'a str,\n body: Element<'a>,\n}}\n\nfn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {{\n cx.render(rsx!(\n a {{\n href: "{{cx.props.href}}",\n class: "fancy-button",\n &cx.props.body\n }}\n ))\n}}\n", + name: "component_element_props.rs".to_string(), + } + p { + "Then, when rendering the component, you can pass in the output of " + code { "cx.render(rsx!(...))" } + ":" + } + CodeBlock { + contents: "
\ncx.render(rsx! {{\n Clickable {{\n href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",\n body: cx.render(rsx!("How to " i {{"not"}} " be seen")),\n }}\n}})\n", + name: "component_element_props.rs".to_string(), + } + blockquote { + p { + "Note: Since " + code { "Element<'a>" } + " is a borrowed prop, there will be no memoization." + } + } + blockquote { + p { + "Warning: While it may compile, do not include the same " + code { "Element" } + " more than once in the RSX. The resulting behavior is unspecified." + } + } + h2 { id: "the-children-field", + Link { + to: BookRoute::DescribingUiComponentChildren { + section: DescribingUiComponentChildrenSection::TheChildrenField, + }, + class: "header", + "The children field" + } + } + p { + "Rather than passing the RSX through a regular prop, you may wish to accept children similarly to how elements can have children. The \"magic\" " + code { "children" } + " prop lets you achieve this:" + } + CodeBlock { + contents: "
\n#[derive(Props)]\nstruct ClickableProps<'a> {{\n href: &'a str,\n children: Element<'a>,\n}}\n\nfn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {{\n cx.render(rsx!(\n a {{\n href: "{{cx.props.href}}",\n class: "fancy-button",\n &cx.props.children\n }}\n ))\n}}\n", + name: "component_children.rs".to_string(), + } + p { + "This makes using the component much simpler: simply put the RSX inside the " + code { "{{}}" } + " brackets – and there is no need for a " + code { "render" } + " call or another macro!" + } + CodeBlock { + contents: "
\ncx.render(rsx! {{\n Clickable {{\n href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",\n "How to " i {{"not"}} " be seen"\n }}\n}})\n", + name: "component_children.rs".to_string(), + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum InteractivityIndexSection { + #[default] + Empty, + Interactivity, +} +impl std::str::FromStr for InteractivityIndexSection { + type Err = InteractivityIndexSectionParseError; + fn from_str(s: &str) -> Result
\ncx.render(rsx! {{\nbutton {{\n onclick: move |event| println!("Clicked! Event: {{event:?}}"),\n "click me!"\n}}\n}})\n", + name: "event_click.rs".to_string(), + } + h2 { id: "the-event-object", + Link { + to: BookRoute::InteractivityEventHandlers { + section: InteractivityEventHandlersSection::TheEventObject, + }, + class: "header", + "The Event object" + } + } + p { + "Event handlers receive an " + Link { to: "https://docs.rs/dioxus-core/latest/dioxus_core/struct.Event.html", + code { "Event" } + } + " object containing information about the event. Different types of events contain different types of data. For example, mouse-related events contain " + Link { to: "https://docs.rs/dioxus/latest/dioxus/events/struct.MouseData.html", + code { "MouseData" } + } + ", which tells you things like where the mouse was clicked and what mouse buttons were used." + } + p { "In the example above, this event data was logged to the terminal:" } + CodeBlock { + contents: "
\nClicked! Event: UiEvent {{ bubble_state: Cell {{ value: true }}, data: MouseData {{ coordinates: Coordinates {{ screen: (242.0, 256.0), client: (26.0, 17.0), element: (16.0, 7.0), page: (26.0, 17.0) }}, modifiers: (empty), held_buttons: EnumSet(), trigger_button: Some(Primary) }} }}\nClicked! Event: UiEvent {{ bubble_state: Cell {{ value: true }}, data: MouseData {{ coordinates: Coordinates {{ screen: (242.0, 256.0), client: (26.0, 17.0), element: (16.0, 7.0), page: (26.0, 17.0) }}, modifiers: (empty), held_buttons: EnumSet(), trigger_button: Some(Primary) }} }}\n", + } + p { + "To learn what the different event types for HTML provide, read the " + Link { to: "https://docs.rs/dioxus-html/latest/dioxus_html/events/index.html", + "events module docs" + } + "." + } + h3 { id: "event-propagation", + Link { + to: BookRoute::InteractivityEventHandlers { + section: InteractivityEventHandlersSection::EventPropagation, + }, + class: "header", + "Event propagation" + } + } + p { + "Some events will trigger first on the element the event originated at upward. For example, a click event on a " + code { "button" } + " inside a " + code { "div" } + " would first trigger the button's event listener and then the div's event listener." + } + blockquote { + p { + "For more information about event propigation see " + Link { to: "https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events#event_bubbling", + "the mdn docs on event bubling" + } + } + } + p { + "If you want to prevent this behavior, you can call " + code { "stop_propogation()" } + " on the event:" + } + CodeBlock { + contents: "
\ncx.render(rsx! {{\ndiv {{\n onclick: move |_event| {{}},\n "outer",\n button {{\n onclick: move |event| {{\n // now, outer won't be triggered\n event.stop_propagation();\n }},\n "inner"\n }}\n}}\n}})\n", + name: "event_nested.rs".to_string(), + } + h2 { id: "prevent-default", + Link { + to: BookRoute::InteractivityEventHandlers { + section: InteractivityEventHandlersSection::PreventDefault, + }, + class: "header", + "Prevent Default" + } + } + p { + "Some events have a default behavior. For keyboard events, this might be entering the typed character. For mouse events, this might be selecting some text." + } + p { + "In some instances, might want to avoid this default behavior. For this, you can add the " + code { "prevent_default" } + " attribute with the name of the handler whose default behavior you want to stop. This attribute is special: you can attach it multiple times for multiple attributes:" + } + CodeBlock { + contents: "
\ncx.render(rsx! {{\ninput {{\n prevent_default: "oninput",\n prevent_default: "onclick",\n}}\n}})\n", + name: "event_prevent_default.rs".to_string(), + } + p { "Any event handlers will still be called." } + blockquote { + p { + "Normally, in React or JavaScript, you'd call \"preventDefault\" on the event in the callback. Dioxus does " + em { "not" } + " currently support this behavior. Note: this means you cannot conditionally prevent default behavior based on the data in the event." + } + } + h2 { id: "handler-props", + Link { + to: BookRoute::InteractivityEventHandlers { + section: InteractivityEventHandlersSection::HandlerProps, + }, + class: "header", + "Handler Props" + } + } + p { + "Sometimes, you might want to make a component that accepts an event handler. A simple example would be a " + code { "FancyButton" } + " component, which accepts an " + code { "on_click" } + " handler:" + } + CodeBlock { + contents: "
\n#[derive(Props)]\npub struct FancyButtonProps<'a> {{\n on_click: EventHandler<'a, MouseEvent>,\n}}\n\npub fn FancyButton<'a>(cx: Scope<'a, FancyButtonProps<'a>>) -> Element<'a> {{\n cx.render(rsx!(button {{\n class: "fancy-button",\n onclick: move |evt| cx.props.on_click.call(evt),\n "click me pls."\n }}))\n}}\n", + name: "event_handler_prop.rs".to_string(), + } + p { "Then, you can use it like any other handler:" } + CodeBlock { + contents: "
\ncx.render(rsx! {{\n FancyButton {{\n on_click: move |event| println!("Clicked! {{event:?}}")\n }}\n}})\n", + name: "event_handler_prop.rs".to_string(), + } + blockquote { + p { + "Note: just like any other attribute, you can name the handlers anything you want! Though they must start with " + code { "on" } + ", for the prop to be automatically turned into an " + code { "EventHandler" } + " at the call site." + } + p { + "You can also put custom data in the event, rather than e.g. " + code { "MouseData" } + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum InteractivityHooksSection { + #[default] + Empty, + HooksAndComponentState, + UseStateHook, + RulesOfHooks, + NoHooksInConditionals, + NoHooksInClosures, + NoHooksInLoops, + UseRefHook, +} +impl std::str::FromStr for InteractivityHooksSection { + type Err = InteractivityHooksSectionParseError; + fn from_str(s: &str) -> Result
\nfn App(cx: Scope) -> Element {{\n // count will be initialized to 0 the first time the component is rendered\n let mut count = use_state(cx, || 0);\n\n cx.render(rsx!(\n h1 {{ "High-Five counter: {{count}}" }}\n button {{\n onclick: move |_| {{\n // changing the count will cause the component to re-render\n count += 1\n }},\n "Up high!"\n }}\n button {{\n onclick: move |_| {{\n // changing the count will cause the component to re-render\n count -= 1\n }},\n "Down low!"\n }}\n ))\n}}\n", + name: "hooks_counter.rs".to_string(), + } + p { + img { + src: asset!("/assets/blog/release-03/counter.png", ImageAssetOptions::new().with_webp()), + alt: "Screenshot: counter app", + title: "", + } + } + p { + "Every time the component's state changes, it re-renders, and the component function is called, so you can describe what you want the new UI to look like. You don't have to worry about \"changing\" anything – just describe what you want in terms of the state, and Dioxus will take care of the rest!" + } + blockquote { + p { + code { "use_state" } + " returns your value wrapped in a smart pointer of type " + Link { to: "https://docs.rs/dioxus/latest/dioxus/prelude/struct.UseState.html", + code { "UseState" } + } + ". This is why you can both read the value and update it, even within an event handler." + } + } + p { "You can use multiple hooks in the same component if you want:" } + CodeBlock { + contents: "
\nfn App(cx: Scope) -> Element {{\n let mut count_a = use_state(cx, || 0);\n let mut count_b = use_state(cx, || 0);\n\n cx.render(rsx!(\n h1 {{ "Counter_a: {{count_a}}" }}\n button {{ onclick: move |_| count_a += 1, "a++" }}\n button {{ onclick: move |_| count_a -= 1, "a--" }}\n h1 {{ "Counter_b: {{count_b}}" }}\n button {{ onclick: move |_| count_b += 1, "b++" }}\n button {{ onclick: move |_| count_b -= 1, "b--" }}\n ))\n}}\n", + name: "hooks_counter_two_state.rs".to_string(), + } + p { + img { + src: asset!( + "/assets/blog/release-03/counter_two_state.png", ImageAssetOptions::new() + .with_webp() + ), + alt: "Screenshot: app with two counters", + title: "", + } + } + h2 { id: "rules-of-hooks", + Link { + to: BookRoute::InteractivityHooks { + section: InteractivityHooksSection::RulesOfHooks, + }, + class: "header", + "Rules of Hooks" + } + } + p { + "The above example might seem a bit magic, since Rust functions are typically not associated with state. Dioxus allows hooks to maintain state across renders through a reference to " + code { "ScopeState" } + ", which is why you must pass " + code { "&cx" } + " to them." + } + p { + "But how can Dioxus differentiate between multiple hooks in the same component? As you saw in the second example, both " + code { "use_state" } + " functions were called with the same parameters, so how come they can return different things when the counters are different?" + } + CodeBlock { + contents: "
\nlet mut count_a = use_state(cx, || 0);\nlet mut count_b = use_state(cx, || 0);\n", + name: "hooks_counter_two_state.rs".to_string(), + } + p { + "This is only possible because the two hooks are always called in the same order, so Dioxus knows which is which. Because the order you call hooks matters, you must follow certain rules when using hooks:" + } + ol { + li { "Hooks may be only used in components or other hooks (we'll get to that later)" } + li { + "On every call to the component function" + ol { + li { "The same hooks must be called" } + li { "In the same order" } + } + } + li { + "Hooks name's should start with " + code { "use_" } + " so you don't accidentally confuse them with regular functions" + } + } + p { "These rules mean that there are certain things you can't do with hooks:" } + h3 { id: "no-hooks-in-conditionals", + Link { + to: BookRoute::InteractivityHooks { + section: InteractivityHooksSection::NoHooksInConditionals, + }, + class: "header", + "No Hooks in Conditionals" + } + } + CodeBlock { + contents: "
\n// ❌ don't call hooks in conditionals!\n// We must ensure that the same hooks will be called every time\n// But `if` statements only run if the conditional is true!\n// So we might violate rule 2.\nif you_are_happy && you_know_it {{\nlet something = use_state(cx, || "hands");\nprintln!("clap your {{something}}")\n}}\n\n// ✅ instead, *always* call use_state\n// You can put other stuff in the conditional though\nlet something = use_state(cx, || "hands");\nif you_are_happy && you_know_it {{\nprintln!("clap your {{something}}")\n}}\n", + name: "hooks_bad.rs".to_string(), + } + h3 { id: "no-hooks-in-closures", + Link { + to: BookRoute::InteractivityHooks { + section: InteractivityHooksSection::NoHooksInClosures, + }, + class: "header", + "No Hooks in Closures" + } + } + CodeBlock { + contents: "
\n// ❌ don't call hooks inside closures!\n// We can't guarantee that the closure, if used, will be called in the same order every time\nlet _a = || {{\nlet b = use_state(cx, || 0);\nb.get()\n}};\n\n// ✅ instead, move hook `b` outside\nlet b = use_state(cx, || 0);\nlet _a = || b.get();\n", + name: "hooks_bad.rs".to_string(), + } + h3 { id: "no-hooks-in-loops", + Link { + to: BookRoute::InteractivityHooks { + section: InteractivityHooksSection::NoHooksInLoops, + }, + class: "header", + "No Hooks in Loops" + } + } + CodeBlock { + contents: "
\n// `names` is a Vec<&str>\n\n// ❌ Do not use hooks in loops!\n// In this case, if the length of the Vec changes, we break rule 2\nfor _name in &names {{\nlet is_selected = use_state(cx, || false);\nprintln!("selected: {{is_selected}}");\n}}\n\n// ✅ Instead, use a hashmap with use_ref\nlet selection_map = use_ref(cx, HashMap::<&str, bool>::new);\n\nfor name in &names {{\nlet is_selected = selection_map.read()[name];\nprintln!("selected: {{is_selected}}");\n}}\n", + name: "hooks_bad.rs".to_string(), + } + h2 { id: "use-ref-hook", + Link { + to: BookRoute::InteractivityHooks { + section: InteractivityHooksSection::UseRefHook, + }, + class: "header", + "use_ref Hook" + } + } + p { + code { "use_state" } + " is great for tracking simple values. However, you may notice in the " + Link { to: "https://docs.rs/dioxus/latest/dioxus/hooks/struct.UseState.html", + code { "UseState" } + " API" + } + " that the only way to modify its value is to replace it with something else (e.g., by calling " + code { "set" } + ", or through one of the " + code { "+=" } + ", " + code { "-=" } + " operators). This works well when it is cheap to construct a value (such as any primitive). But what if you want to maintain more complex data in the components state?" + } + p { + "For example, suppose we want to maintain a " + code { "Vec" } + " of values. If we stored it with " + code { "use_state" } + ", the only way to add a new value to the list would be to create a new " + code { "Vec" } + " with the additional value, and put it in the state. This is expensive! We want to modify the existing " + code { "Vec" } + " instead." + } + p { + "Thankfully, there is another hook for that, " + code { "use_ref" } + "! It is similar to " + code { "use_state" } + ", but it lets you get a mutable reference to the contained data." + } + p { + "Here's a simple example that keeps a list of events in a " + code { "use_ref" } + ". We can acquire write access to the state with " + code { ".with_mut()" } + ", and then just " + code { ".push" } + " a new value to the state:" + } + CodeBlock { + contents: "
\nfn App(cx: Scope) -> Element {{\n let list = use_ref(cx, Vec::new);\n\n cx.render(rsx!(\n p {{ "Current list: {{list.read():?}}" }}\n button {{\n onclick: move |event| {{\n list.with_mut(|list| list.push(event));\n }},\n "Click me!"\n }}\n ))\n}}\n", + name: "hooks_use_ref.rs".to_string(), + } + blockquote { + p { + "The return values of " + code { "use_state" } + " and " + code { "use_ref" } + " ( " + code { "UseState" } + " and " + code { "UseRef" } + ", respectively) are in some ways similar to " + Link { to: "https://doc.rust-lang.org/std/cell/", + code { "Cell" } + } + " and " + Link { to: "https://doc.rust-lang.org/std/cell/struct.RefCell.html", + code { "RefCell" } + } + " – they provide interior mutability. However, these Dioxus wrappers also ensure that the component gets re-rendered whenever you change the state." + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum InteractivityUserInputSection { + #[default] + Empty, + UserInput, + ControlledInputs, + UncontrolledInputs, +} +impl std::str::FromStr for InteractivityUserInputSection { + type Err = InteractivityUserInputSectionParseError; + fn from_str(s: &str) -> Result
\nfn App(cx: Scope) -> Element {{\n let name = use_state(cx, || "bob".to_string());\n\n cx.render(rsx! {{\n input {{\n // we tell the component what to render\n value: "{{name}}",\n // and what to do when the value changes\n oninput: move |evt| name.set(evt.value.clone()),\n }}\n }})\n}}\n", + name: "input_controlled.rs".to_string(), + } + p { "Notice the flexibility – you can:" } + ul { + li { "Also display the same contents in another element, and they will be in sync" } + li { "Transform the input every time it is modified (e.g. to make sure it is upper case)" } + li { "Validate the input every time it changes" } + li { + "Have custom logic happening when the input changes (e.g. network request for autocompletion)" + } + li { + "Programmatically change the value (e.g. a \"randomize\" button that fills the input with nonsense)" + } + } + h2 { id: "uncontrolled-inputs", + Link { + to: BookRoute::InteractivityUserInput { + section: InteractivityUserInputSection::UncontrolledInputs, + }, + class: "header", + "Uncontrolled Inputs" + } + } + p { + "As an alternative to controlled inputs, you can simply let the platform keep track of the input values. If we don't tell a HTML input what content it should have, it will be editable anyway (this is built into the browser). This approach can be more performant, but less flexible. For example, it's harder to keep the input in sync with another element." + } + p { + "Since you don't necessarily have the current value of the uncontrolled input in state, you can access it either by listening to " + code { "oninput" } + " events (similarly to controlled components), or, if the input is part of a form, you can access the form data in the form events (e.g. " + code { "oninput" } + " or " + code { "onsubmit" } + "):" + } + CodeBlock { + contents: "
\nfn App(cx: Scope) -> Element {{\n cx.render(rsx! {{\n form {{\n onsubmit: move |event| {{\n println!("Submitted! {{event:?}}")\n }},\n input {{ name: "name", }},\n input {{ name: "age", }},\n input {{ name: "date", }},\n input {{ r#type: "submit", }},\n }}\n }})\n}}\n", + name: "input_uncontrolled.rs".to_string(), + } + CodeBlock { contents: "
\nSubmitted! UiEvent {{ data: FormData {{ value: "", values: {{"age": "very old", "date": "1966", "name": "Fred"}} }} }}\n" } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum InteractivitySharingStateSection { + #[default] + Empty, + SharingState, + LiftingState, + UsingContext, +} +impl std::str::FromStr for InteractivitySharingStateSection { + type Err = InteractivitySharingStateSectionParseError; + fn from_str(s: &str) -> Result
\n#[inline_props]\nfn Meme<'a>(cx: Scope<'a>, caption: &'a str) -> Element<'a> {{\n let container_style = r#"\n position: relative;\n width: fit-content;\n "#;\n\n let caption_container_style = r#"\n position: absolute;\n bottom: 0;\n left: 0;\n right: 0;\n padding: 16px 8px;\n "#;\n\n let caption_style = r"\n font-size: 32px;\n margin: 0;\n color: white;\n text-align: center;\n ";\n\n cx.render(rsx!(\n div {{\n style: "{{container_style}}",\n img {{\n src: "https://i.imgflip.com/2zh47r.jpg",\n height: "500px",\n }},\n div {{\n style: "{{caption_container_style}}",\n p {{\n style: "{{caption_style}}",\n "{{caption}}"\n }}\n }}\n }}\n ))\n}}\n", + name: "meme_editor.rs".to_string(), + } + blockquote { + p { + "Note that the " + code { "Meme" } + " component is unaware where the caption is coming from – it could be stored in " + code { "use_state" } + ", " + code { "use_ref" } + ", or a constant. This ensures that it is very reusable – the same component can be used for a meme gallery without any changes!" + } + } + p { + "We also create a caption editor, completely decoupled from the meme. The caption editor must not store the caption itself – otherwise, how will we provide it to the " + code { "Meme" } + " component? Instead, it should accept the current caption as a prop, as well as an event handler to delegate input events to:" + } + CodeBlock { + contents: "
\n#[inline_props]\nfn CaptionEditor<'a>(\n cx: Scope<'a>,\n caption: &'a str,\n on_input: EventHandler<'a, FormEvent>,\n) -> Element<'a> {{\n let input_style = r"\n border: none;\n background: cornflowerblue;\n padding: 8px 16px;\n margin: 0;\n border-radius: 4px;\n color: white;\n ";\n\n cx.render(rsx!(input {{\n style: "{{input_style}}",\n value: "{{caption}}",\n oninput: move |event| on_input.call(event),\n }}))\n}}\n", + name: "meme_editor.rs".to_string(), + } + p { + "Finally, a third component will render the other two as children. It will be responsible for keeping the state and passing down the relevant props." + } + CodeBlock { + contents: "
\nfn MemeEditor(cx: Scope) -> Element {{\n let container_style = r"\n display: flex;\n flex-direction: column;\n gap: 16px;\n margin: 0 auto;\n width: fit-content;\n ";\n\n let caption = use_state(cx, || "me waiting for my rust code to compile".to_string());\n\n cx.render(rsx! {{\n div {{\n style: "{{container_style}}",\n h1 {{ "Meme Editor" }},\n Meme {{\n caption: caption,\n }},\n CaptionEditor {{\n caption: caption,\n on_input: move |event: FormEvent| {{caption.set(event.value.clone());}},\n }},\n }}\n }})\n}}\n", + name: "meme_editor.rs".to_string(), + } + p { + img { + src: asset!( + "/assets/blog/release-03/meme_editor_screenshot.png", ImageAssetOptions::new() + .with_webp() + ), + alt: "Meme Editor Screenshot: An old plastic skeleton sitting on a park bench. Caption: \"me waiting for a language feature\"", + title: "", + } + } + h2 { id: "using-context", + Link { + to: BookRoute::InteractivitySharingState { + section: InteractivitySharingStateSection::UsingContext, + }, + class: "header", + "Using Context" + } + } + p { + "Sometimes, some state needs to be shared between multiple components far down the tree, and passing it down through props is very inconvenient." + } + p { + "Suppose now that we want to implement a dark mode toggle for our app. To achieve this, we will make every component select styling depending on whether dark mode is enabled or not." + } + blockquote { + p { + "Note: we're choosing this approach for the sake of an example. There are better ways to implement dark mode (e.g. using CSS variables). Let's pretend CSS variables don't exist – welcome to 2013!" + } + } + p { + "Now, we could write another " + code { "use_state" } + " in the top component, and pass " + code { "is_dark_mode" } + " down to every component through props. But think about what will happen as the app grows in complexity – almost every component that renders any CSS is going to need to know if dark mode is enabled or not – so they'll all need the same dark mode prop. And every parent component will need to pass it down to them. Imagine how messy and verbose that would get, especially if we had components several levels deep!" + } + p { + "Dioxus offers a better solution than this \"prop drilling\" – providing context. The " + Link { to: "https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_context_provider.html", + code { "use_context_provider" } + } + " hook is similar to " + code { "use_ref" } + ", but it makes it available through " + Link { to: "https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_context.html", + code { "use_context" } + } + " for all children components." + } + p { "First, we have to create a struct for our dark mode configuration:" } + CodeBlock { + contents: "
\nstruct DarkMode(bool);\n", + name: "meme_editor_dark_mode.rs".to_string(), + } + p { + "Now, in a top-level component (like " + code { "App" } + "), we can provide the " + code { "DarkMode" } + " context to all children components:" + } + CodeBlock { + contents: "
\nuse_shared_state_provider(cx, || DarkMode(false));\n", + name: "meme_editor_dark_mode.rs".to_string(), + } + p { + "As a result, any child component of " + code { "App" } + " (direct or not), can access the " + code { "DarkMode" } + " context." + } + CodeBlock { + contents: "
\nlet dark_mode_context = use_shared_state::<DarkMode>(cx);\n", + name: "meme_editor_dark_mode.rs".to_string(), + } + blockquote { + p { + code { "use_context" } + " returns " + code { "Option
\npub fn DarkModeToggle(cx: Scope) -> Element {{\n let dark_mode = use_shared_state::<DarkMode>(cx).unwrap();\n\n let style = if dark_mode.read().0 {{\n "color:white"\n }} else {{\n ""\n }};\n\n cx.render(rsx!(label {{\n style: "{{style}}",\n "Dark Mode",\n input {{\n r#type: "checkbox",\n oninput: move |event| {{\n let is_enabled = event.value == "true";\n dark_mode.write().0 = is_enabled;\n }},\n }},\n }}))\n}}\n", + name: "meme_editor_dark_mode.rs".to_string(), + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum InteractivityCustomHooksSection { + #[default] + Empty, + CustomHooks, + ComposingHooks, + CustomHookLogic, +} +impl std::str::FromStr for InteractivityCustomHooksSection { + type Err = InteractivityCustomHooksSectionParseError; + fn from_str(s: &str) -> Result
\nfn use_settings(cx: &ScopeState) -> UseSharedState<AppSettings> {{\n use_shared_state::<AppSettings>(cx).expect("App settings not provided")\n}}\n", + name: "hooks_composed.rs".to_string(), + } + h2 { id: "custom-hook-logic", + Link { + to: BookRoute::InteractivityCustomHooks { + section: InteractivityCustomHooksSection::CustomHookLogic, + }, + class: "header", + "Custom Hook Logic" + } + } + p { + "You can use " + Link { to: "https://docs.rs/dioxus/latest/dioxus/prelude/struct.Scope.html#method.use_hook", + code { "cx.use_hook" } + } + " to build your own hooks. In fact, this is what all the standard hooks are built on!" + } + p { + code { "use_hook" } + " accepts a single closure for initializing the hook. It will be only run the first time the component is rendered. The return value of that closure will be used as the value of the hook – Dioxus will take it, and store it for as long as the component is alive. On every render (not just the first one!), you will get a reference to this value." + } + blockquote { + p { + "Note: You can implement " + Link { to: "https://doc.rust-lang.org/std/ops/trait.Drop.html", + code { "Drop" } + } + " for your hook value – it will be dropped then the component is unmounted (no longer in the UI)" + } + } + p { + "Inside the initialization closure, you will typically make calls to other " + code { "cx" } + " methods. For example:" + } + ul { + li { + "The " + code { "use_state" } + " hook tracks state in the hook value, and uses " + Link { to: "https://docs.rs/dioxus/latest/dioxus/prelude/struct.Scope.html#method.schedule_update", + code { "cx.schedule_update" } + } + " to make Dioxus re-render the component whenever it changes." + } + li { + "The " + code { "use_context" } + " hook calls " + Link { to: "https://docs.rs/dioxus/latest/dioxus/prelude/struct.Scope.html#method.consume_context", + code { "cx.consume_context" } + } + " (which would be expensive to call on every render) to get some context from the scope" + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum InteractivityDynamicRenderingSection { + #[default] + Empty, + DynamicRendering, + ConditionalRendering, + ImprovingTheIfElseExample, + InspectingElementProps, + RenderingNothing, + RenderingLists, + InlineForLoops, + TheKeyAttribute, +} +impl std::str::FromStr for InteractivityDynamicRenderingSection { + type Err = InteractivityDynamicRenderingSectionParseError; + fn from_str(s: &str) -> Result
\nif *is_logged_in {{\ncx.render(rsx! {{\n "Welcome!"\n button {{\n onclick: move |_| on_log_out.call(()),\n "Log Out",\n }}\n}})\n}} else {{\ncx.render(rsx! {{\n button {{\n onclick: move |_| on_log_in.call(()),\n "Log In",\n }}\n}})\n}}\n", + name: "conditional_rendering.rs".to_string(), + } + blockquote { + p { + "You could also use " + code { "match" } + " statements, or any Rust function to conditionally render different things." + } + } + h3 { id: "improving-the-if-else-example", + Link { + to: BookRoute::InteractivityDynamicRendering { + section: InteractivityDynamicRenderingSection::ImprovingTheIfElseExample, + }, + class: "header", + "Improving the if-else Example" + } + } + p { + "You may have noticed some repeated code in the " + code { "if-else" } + " example above. Repeating code like this is both bad for maintainability and performance. Dioxus will skip diffing static elements like the button, but when switching between multiple " + code { "rsx" } + " calls it cannot perform this optimization. For this example either approach is fine, but for components with large parts that are reused between conditionals, it can be more of an issue." + } + p { + "We can improve this example by splitting up the dynamic parts and inserting them where they are needed." + } + CodeBlock { + contents: "
\ncx.render(rsx! {{\n// We only render the welcome message if we are logged in\n// You can use if statements in the middle of a render block to conditionally render elements\nif *is_logged_in {{\n // Notice the body of this if statment is rsx code, not an expression\n "Welcome!"\n}}\nbutton {{\n // depending on the value of `is_logged_in`, we will call a different event handler\n onclick: move |_| if *is_logged_in {{\n on_log_in.call(())\n }}\n else{{\n on_log_out.call(())\n }},\n if *is_logged_in {{\n // if we are logged in, the button should say "Log Out"\n "Log Out"\n }} else {{\n // if we are not logged in, the button should say "Log In"\n "Log In"\n }}\n}}\n}})\n", + name: "conditional_rendering.rs".to_string(), + } + h3 { id: "inspecting-element-props", + Link { + to: BookRoute::InteractivityDynamicRendering { + section: InteractivityDynamicRenderingSection::InspectingElementProps, + }, + class: "header", + "Inspecting Element props" + } + } + p { + "Since " + code { "Element" } + " is a " + code { "Option
\nfn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {{\n match cx.props.children {{\n Some(VNode {{ dynamic_nodes, .. }}) => {{\n todo!("render some stuff")\n }}\n _ => {{\n todo!("render some other stuff")\n }}\n }}\n}}\n", + name: "component_children_inspect.rs".to_string(), + } + p { + "You can't mutate the " + code { "Element" } + ", but if you need a modified version of it, you can construct a new one based on its attributes/children/etc." + } + h2 { id: "rendering-nothing", + Link { + to: BookRoute::InteractivityDynamicRendering { + section: InteractivityDynamicRenderingSection::RenderingNothing, + }, + class: "header", + "Rendering Nothing" + } + } + p { + "To render nothing, you can return " + code { "None" } + " from a component. This is useful if you want to conditionally hide something:" + } + CodeBlock { + contents: "
\nif *is_logged_in {{\nreturn None;\n}}\n\ncx.render(rsx! {{\na {{\n "You must be logged in to comment"\n}}\n}})\n", + name: "conditional_rendering.rs".to_string(), + } + p { + "This works because the " + code { "Element" } + " type is just an alias for " + code { "Option
\nlet comment_field = use_state(cx, String::new);\nlet mut next_id = use_state(cx, || 0);\nlet comments = use_ref(cx, Vec::<Comment>::new);\n\nlet comments_lock = comments.read();\nlet comments_rendered = comments_lock.iter().map(|comment| {{\nrsx!(CommentComponent {{\n key: "{{comment.id}}",\n comment: comment.clone(),\n}})\n}});\n\ncx.render(rsx!(\nform {{\n onsubmit: move |_| {{\n comments.write().push(Comment {{\n content: comment_field.get().clone(),\n id: *next_id.get(),\n }});\n next_id += 1;\n\n comment_field.set(String::new());\n }},\n input {{\n value: "{{comment_field}}",\n oninput: |event| comment_field.set(event.value.clone()),\n }}\n input {{\n r#type: "submit",\n }}\n}},\ncomments_rendered,\n))\n", + name: "rendering_lists.rs".to_string(), + } + h3 { id: "inline-for-loops", + Link { + to: BookRoute::InteractivityDynamicRendering { + section: InteractivityDynamicRenderingSection::InlineForLoops, + }, + class: "header", + "Inline for loops" + } + } + p { + "Because of how common it is to render a list of items, Dioxus provides a shorthand for this. Instead of using " + code { ".iter, " } + ".map " + code { ", and " } + "rsx " + code { ", you can use a " } + "for" + " " + "`" + " loop with a body of rsx code:" + } + CodeBlock { + contents: "
\nlet comment_field = use_state(cx, String::new);\nlet mut next_id = use_state(cx, || 0);\nlet comments = use_ref(cx, Vec::<Comment>::new);\n\ncx.render(rsx!(\nform {{\n onsubmit: move |_| {{\n comments.write().push(Comment {{\n content: comment_field.get().clone(),\n id: *next_id.get(),\n }});\n next_id += 1;\n\n comment_field.set(String::new());\n }},\n input {{\n value: "{{comment_field}}",\n oninput: |event| comment_field.set(event.value.clone()),\n }}\n input {{\n r#type: "submit",\n }}\n}},\nfor comment in &*comments.read() {{\n // Notice the body of this for loop is rsx code, not an expression\n CommentComponent {{\n key: "{{comment.id}}",\n comment: comment.clone(),\n }}\n}}\n))\n", + name: "rendering_lists.rs".to_string(), + } + h3 { id: "the-key-attribute", + Link { + to: BookRoute::InteractivityDynamicRendering { + section: InteractivityDynamicRenderingSection::TheKeyAttribute, + }, + class: "header", + "The key Attribute" + } + } + p { + "Every time you re-render your list, Dioxus needs to keep track of which items go where to determine what updates need to be made to the UI." + } + p { + "For example, suppose the " + code { "CommentComponent" } + " had some state – e.g. a field where the user typed in a reply. If the order of comments suddenly changes, Dioxus needs to correctly associate that state with the same comment – otherwise, the user will end up replying to a different comment!" + } + p { + "To help Dioxus keep track of list items, we need to associate each item with a unique key. In the example above, we dynamically generated the unique key. In real applications, it's more likely that the key will come from e.g. a database ID. It doesn't matter where you get the key from, as long as it meets the requirements:" + } + ul { + li { "Keys must be unique in a list" } + li { "The same item should always get associated with the same key" } + li { + "Keys should be relatively small (i.e. converting the entire Comment structure to a String would be a pretty bad key) so they can be compared efficiently" + } + } + p { + "You might be tempted to use an item's index in the list as its key. That’s what Dioxus will use if you don’t specify a key at all. This is only acceptable if you can guarantee that the list is constant – i.e., no re-ordering, additions, or deletions." + } + blockquote { + p { + "Note that if you pass the key to a component you've made, it won't receive the key as a prop. It’s only used as a hint by Dioxus itself. If your component needs an ID, you have to pass it as a separate prop." + } + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum InteractivityRouterSection { + #[default] + Empty, + Router, + WhatIsIt, + UsingTheRouter, + Links, + MoreReading, +} +impl std::str::FromStr for InteractivityRouterSection { + type Err = InteractivityRouterSectionParseError; + fn from_str(s: &str) -> Result
\ncargo add dioxus-router\n" } + h2 { id: "using-the-router", + Link { + to: BookRoute::InteractivityRouter { + section: InteractivityRouterSection::UsingTheRouter, + }, + class: "header", + "Using the router" + } + } + p { + "Unlike other routers in the Rust ecosystem, our router is built declaratively. This makes it possible to compose our app layout simply by arranging components." + } + CodeBlock { + contents: "
\nrsx!{{\n // All of our routes will be rendered inside this Router component\n Router {{\n // if the current location is "/home", render the Home component\n Route {{ to: "/home", Home {{}} }}\n // if the current location is "/blog", render the Blog component\n Route {{ to: "/blog", Blog {{}} }}\n }}\n}}\n", + } + p { + "Whenever we visit this app, we will get either the Home component or the Blog component rendered depending on which route we enter at. If neither of these routes match the current location, then nothing will render." + } + p { "We can fix this one of two ways:" } + ul { + li { "A fallback 404 page" } + } + CodeBlock { contents: "
\nrsx!{{\n Router {{\n Route {{ to: "/home", Home {{}} }}\n Route {{ to: "/blog", Blog {{}} }}\n // if the current location doesn't match any of the above routes, render the NotFound component\n Route {{ to: "", NotFound {{}} }}\n }}\n}}\n" } + ul { + li { "Redirect 404 to home" } + } + CodeBlock { + contents: "
\nrsx!{{\n Router {{\n Route {{ to: "/home", Home {{}} }}\n Route {{ to: "/blog", Blog {{}} }}\n // if the current location doesn't match any of the above routes, redirect to "/home"\n Redirect {{ from: "", to: "/home" }}\n }}\n}}\n", + } + h2 { id: "links", + Link { + to: BookRoute::InteractivityRouter { + section: InteractivityRouterSection::Links, + }, + class: "header", + "Links" + } + } + p { + "For our app to navigate these routes, we can provide clickable elements called Links. These simply wrap " + code { "" } + " elements that, when clicked, navigate the app to the given location." + } + CodeBlock { contents: "
\nrsx!{{\n Link {{\n to: "/home",\n "Go home!"\n }}\n}}\n" } + h2 { id: "more-reading", + Link { + to: BookRoute::InteractivityRouter { + section: InteractivityRouterSection::MoreReading, + }, + class: "header", + "More reading" + } + } + p { + "This page is just a very brief overview of the router. For more information, check out " + Link { to: "https://dioxuslabs.com/router/guide/", "the router book" } + " or some of " + Link { to: "https://github.com/DioxusLabs/dioxus/blob/master/examples/router.rs", + "the router examples" + } + "." + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum AsyncIndexSection { + #[default] + Empty, + WorkingWithAsync, + TheRuntime, +} +impl std::str::FromStr for AsyncIndexSection { + type Err = AsyncIndexSectionParseError; + fn from_str(s: &str) -> Result
\nlet future = use_future(cx, (), |_| async move {{\n reqwest::get("https://dog.ceo/api/breeds/image/random")\n .await\n .unwrap()\n .json::<ApiResponse>()\n .await\n}});\n", + name: "use_future.rs".to_string(), + } + p { + "The code inside " + code { "use_future" } + " will be submitted to the Dioxus scheduler once the component has rendered." + } + p { + "We can use " + code { ".value()" } + " to get the result of the future. On the first run, since there's no data ready when the component loads, its value will be " + code { "None" } + ". However, once the future is finished, the component will be re-rendered and the value will now be " + code { "Some(...)" } + ", containing the return value of the closure." + } + p { "We can then render that result:" } + CodeBlock { + contents: "
\ncx.render(match future.value() {{\n Some(Ok(response)) => rsx! {{\n button {{\n onclick: move |_| future.restart(),\n "Click to fetch another doggo"\n }}\n div {{\n img {{\n max_width: "500px",\n max_height: "500px",\n src: "{{response.image_url}}",\n }}\n }}\n }},\n Some(Err(_)) => rsx! {{ div {{ "Loading dogs failed" }} }},\n None => rsx! {{ div {{ "Loading dogs..." }} }},\n}})\n", + name: "use_future.rs".to_string(), + } + h2 { id: "restarting-the-future", + Link { + to: BookRoute::AsyncUseFuture { + section: AsyncUseFutureSection::RestartingTheFuture, + }, + class: "header", + "Restarting the Future" + } + } + p { + "The " + code { "UseFuture" } + " handle provides a " + code { "restart" } + " method. It can be used to execute the future again, producing a new value." + } + h2 { id: "dependencies", + Link { + to: BookRoute::AsyncUseFuture { + section: AsyncUseFutureSection::Dependencies, + }, + class: "header", + "Dependencies" + } + } + p { + "Often, you will need to run the future again every time some value (e.g. a prop) changes. Rather than calling " + code { "restart" } + " manually, you can provide a tuple of \"dependencies\" to the hook. It will automatically re-run the future when any of those dependencies change. Example:" + } + CodeBlock { + contents: "
\nlet future = use_future(cx, (breed,), |(breed,)| async move {{\n reqwest::get(format!("https://dog.ceo/api/breed/{{breed}}/images/random"))\n .await\n .unwrap()\n .json::<ApiResponse>()\n .await\n}});\n", + name: "use_future.rs".to_string(), + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum AsyncUseCoroutineSection { + #[default] + Empty, + Coroutines, + UseCoroutine, + YieldingValues, + SendingValues, + AutomaticInjectionIntoTheContextApi, +} +impl std::str::FromStr for AsyncUseCoroutineSection { + type Err = AsyncUseCoroutineSectionParseError; + fn from_str(s: &str) -> Result
\nfn app(cx: Scope) -> Element {{\n let ws: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {{\n // Connect to some sort of service\n let mut conn = connect_to_ws_server().await;\n\n // Wait for data on the service\n while let Some(msg) = conn.next().await {{\n // handle messages\n }}\n }});\n}}\n", + } + p { "For many services, a simple async loop will handle the majority of use cases." } + p { + "However, if we want to temporarily disable the coroutine, we can \"pause\" it using the " + code { "pause" } + " method, and \"resume\" it using the " + code { "resume" } + " method:" + } + CodeBlock { + contents: "
\nlet sync: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {{\n // code for syncing\n}});\n\nif sync.is_running() {{\n cx.render(rsx!{{\n button {{\n onclick: move |_| sync.pause(),\n "Disable syncing"\n }}\n }})\n}} else {{\n cx.render(rsx!{{\n button {{\n onclick: move |_| sync.resume(),\n "Enable syncing"\n }}\n }})\n}}\n", + } + p { + "This pattern is where coroutines are extremely useful – instead of writing all the complicated logic for pausing our async tasks like we would with JavaScript promises, the Rust model allows us to just not poll our future." + } + h2 { id: "yielding-values", + Link { + to: BookRoute::AsyncUseCoroutine { + section: AsyncUseCoroutineSection::YieldingValues, + }, + class: "header", + "Yielding Values" + } + } + p { + "To yield values from a coroutine, simply bring in a " + code { "UseState" } + " handle and set the value whenever your coroutine completes its work." + } + p { + "The future must be " + code { "'static" } + " – so any values captured by the task cannot carry any references to " + code { "cx" } + ", such as a " + code { "UseState" } + "." + } + p { + "You can use " + Link { to: "https://doc.rust-lang.org/std/borrow/trait.ToOwned.html#tymethod.to_owned", + "to_owned" + } + " to create a clone of the hook handle which can be moved into the async closure." + } + CodeBlock { + contents: "
\nlet sync_status = use_state(cx, || Status::Launching);\nlet sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {{\n let sync_status = sync_status.to_owned();\n async move {{\n loop {{\n delay_ms(1000).await;\n sync_status.set(Status::Working);\n }}\n }}\n}})\n", + } + p { + "To make this a bit less verbose, Dioxus exports the " + code { "to_owned!" } + " macro which will create a binding as shown above, which can be quite helpful when dealing with many values." + } + CodeBlock { + contents: "
\nlet sync_status = use_state(cx, || Status::Launching);\nlet load_status = use_state(cx, || Status::Launching);\nlet sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {{\n to_owned![sync_status, load_status];\n async move {{\n // ...\n }}\n}})\n", + } + h2 { id: "sending-values", + Link { + to: BookRoute::AsyncUseCoroutine { + section: AsyncUseCoroutineSection::SendingValues, + }, + class: "header", + "Sending Values" + } + } + p { + "You might've noticed the " + code { "use_coroutine" } + " closure takes an argument called " + code { "rx" } + ". What is that? Well, a common pattern in complex apps is to handle a bunch of async code at once. With libraries like Redux Toolkit, managing multiple promises at once can be challenging and a common source of bugs." + } + p { + "With Coroutines, we can centralize our async logic. The " + code { "rx" } + " parameter is an Channel that allows code external to the coroutine to send data " + em { "into" } + " the coroutine. Instead of looping on an external service, we can loop on the channel itself, processing messages from within our app without needing to spawn a new future. To send data into the coroutine, we would call \"send\" on the handle." + } + CodeBlock { + contents: "
\nenum ProfileUpdate {{\n SetUsername(String),\n SetAge(i32)\n}}\n\nlet profile = use_coroutine(cx, |mut rx: UnboundedReciver<ProfileUpdate>| async move {{\n let mut server = connect_to_server().await;\n\n while let Ok(msg) = rx.next().await {{\n match msg {{\n ProfileUpdate::SetUsername(name) => server.update_username(name).await,\n ProfileUpdate::SetAge(age) => server.update_age(age).await,\n }}\n }}\n}});\n\n\ncx.render(rsx!{{\n button {{\n onclick: move |_| profile.send(ProfileUpdate::SetUsername("Bob".to_string())),\n "Update username"\n }}\n}})\n", + } + p { + "For sufficiently complex apps, we could build a bunch of different useful \"services\" that loop on channels to update the app." + } + CodeBlock { + contents: "
\nlet profile = use_coroutine(cx, profile_service);\nlet editor = use_coroutine(cx, editor_service);\nlet sync = use_coroutine(cx, sync_service);\n\nasync fn profile_service(rx: UnboundedReceiver<ProfileCommand>) {{\n // do stuff\n}}\n\nasync fn sync_service(rx: UnboundedReceiver<SyncCommand>) {{\n // do stuff\n}}\n\nasync fn editor_service(rx: UnboundedReceiver<EditorCommand>) {{\n // do stuff\n}}\n", + } + p { + "We can combine coroutines with " + Link { to: "https://docs.rs/fermi/latest/fermi/index.html", "Fermi" } + " to emulate Redux Toolkit's Thunk system with much less headache. This lets us store all of our app's state " + em { "within" } + " a task and then simply update the \"view\" values stored in Atoms. It cannot be understated how powerful this technique is: we get all the perks of native Rust tasks with the optimizations and ergonomics of global state. This means your " + em { "actual" } + " state does not need to be tied up in a system like Fermi or Redux – the only Atoms that need to exist are those that are used to drive the display/UI." + } + CodeBlock { + contents: "
\nstatic USERNAME: Atom<String> = |_| "default".to_string();\n\nfn app(cx: Scope) -> Element {{\n let atoms = use_atom_root(cx);\n\n use_coroutine(cx, |rx| sync_service(rx, atoms.clone()));\n\n cx.render(rsx!{{\n Banner {{}}\n }})\n}}\n\nfn Banner(cx: Scope) -> Element {{\n let username = use_read(cx, USERNAME);\n\n cx.render(rsx!{{\n h1 {{ "Welcome back, {{username}}" }}\n }})\n}}\n", + } + p { + "Now, in our sync service, we can structure our state however we want. We only need to update the view values when ready." + } + CodeBlock { + contents: "
\nenum SyncAction {{\n SetUsername(String),\n}}\n\nasync fn sync_service(mut rx: UnboundedReceiver<SyncAction>, atoms: AtomRoot) {{\n let username = atoms.write(USERNAME);\n let errors = atoms.write(ERRORS);\n\n while let Ok(msg) = rx.next().await {{\n match msg {{\n SyncAction::SetUsername(name) => {{\n if set_name_on_server(&name).await.is_ok() {{\n username.set(name);\n }} else {{\n errors.make_mut().push("SetUsernameFailed");\n }}\n }}\n }}\n }}\n}}\n", + } + h2 { id: "automatic-injection-into-the-context-api", + Link { + to: BookRoute::AsyncUseCoroutine { + section: AsyncUseCoroutineSection::AutomaticInjectionIntoTheContextApi, + }, + class: "header", + "Automatic injection into the Context API" + } + } + p { + "Coroutine handles are automatically injected through the context API. You can use the " + code { "use_coroutine_handle" } + " hook with the message type as a generic to fetch a handle." + } + CodeBlock { contents: "
\nfn Child(cx: Scope) -> Element {{\n let sync_task = use_coroutine_handle::<SyncAction>(cx);\n\n sync_task.send(SyncAction::SetUsername);\n}}\n" } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum AsyncSpawnSection { + #[default] + Empty, + SpawningFutures, + SpawningTokioTasks, +} +impl std::str::FromStr for AsyncSpawnSection { + type Err = AsyncSpawnSectionParseError; + fn from_str(s: &str) -> Result
\nlet logged_in = use_state(cx, || false);\n\nlet log_in = move |_| {{\n cx.spawn({{\n let logged_in = logged_in.to_owned();\n\n async move {{\n let resp = reqwest::Client::new()\n .post("http://example.com/login")\n .send()\n .await;\n\n match resp {{\n Ok(_data) => {{\n println!("Login successful!");\n logged_in.set(true);\n }}\n Err(_err) => {{\n println!(\n "Login failed - you need a login server running on localhost:8080."\n )\n }}\n }}\n }}\n }});\n}};\n\ncx.render(rsx! {{\n button {{\n onclick: log_in,\n "Login",\n }}\n}})\n", + name: "spawn.rs".to_string(), + } + blockquote { + p { + "Note: " + code { "spawn" } + " will always spawn a " + em { "new" } + " future. You most likely don't want to call it on every render." + } + } + p { + "Calling " + code { "spawn" } + " will give you a " + code { "JoinHandle" } + " which lets you cancel or pause the future." + } + h2 { id: "spawning-tokio-tasks", + Link { + to: BookRoute::AsyncSpawn { + section: AsyncSpawnSection::SpawningTokioTasks, + }, + class: "header", + "Spawning Tokio Tasks" + } + } + p { + "Sometimes, you might want to spawn a background task that needs multiple threads or talk to hardware that might block your app code. In these cases, we can directly spawn a Tokio task from our future. For Dioxus-Desktop, your task will be spawned onto Tokio's Multithreaded runtime:" + } + CodeBlock { + contents: "
\ncx.spawn(async {{\n let _ = tokio::spawn(async {{}}).await;\n\n let _ = tokio::task::spawn_local(async {{\n // some !Send work\n }})\n .await;\n}});\n", + name: "spawn.rs".to_string(), + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum BestPracticesIndexSection { + #[default] + Empty, + BestPractices, + ReusableComponents, + MinimizeStateDependencies, +} +impl std::str::FromStr for BestPracticesIndexSection { + type Err = BestPracticesIndexSectionParseError; + fn from_str(s: &str) -> Result
\nfn App(cx: Scope) -> Element {{\n None\n}}\n" } + p { + "This lets us add in some syntactic sugar for operations we think " + em { "shouldn't" } + " fail, but we're still not confident enough to \"unwrap\" on." + } + blockquote { + p { + "The nature of " + code { "Option
\nfn App(cx: Scope) -> Element {{\n // immediately return "None"\n let name = cx.use_hook(|_| Some("hi"))?;\n}}\n", + } + h2 { id: "early-return-on-result", + Link { + to: BookRoute::BestPracticesErrorHandling { + section: BestPracticesErrorHandlingSection::EarlyReturnOnResult, + }, + class: "header", + "Early return on result" + } + } + p { + "Because Rust can't accept both Options and Results with the existing try infrastructure, you'll need to manually handle Results. This can be done by converting them into Options or by explicitly handling them." + } + CodeBlock { + contents: "
\nfn App(cx: Scope) -> Element {{\n // Convert Result to Option\n let name = cx.use_hook(|_| "1.234").parse().ok()?;\n\n\n // Early return\n let count = cx.use_hook(|_| "1.234");\n let val = match count.parse() {{\n Ok(val) => val\n Err(err) => return cx.render(rsx!{{ "Parsing failed" }})\n }};\n}}\n", + } + p { + "Notice that while hooks in Dioxus do not like being called in conditionals or loops, they " + em { "are" } + " okay with early returns. Returning an error state early is a completely valid way of handling errors." + } + h2 { id: "match-results", + Link { + to: BookRoute::BestPracticesErrorHandling { + section: BestPracticesErrorHandlingSection::MatchResults, + }, + class: "header", + "Match results" + } + } + p { + "The next \"best\" way of handling errors in Dioxus is to match on the error locally. This is the most robust way of handling errors, though it doesn't scale to architectures beyond a single component." + } + p { "To do this, we simply have an error state built into our component:" } + CodeBlock { contents: "
\nlet err = use_state(cx, || None);\n" } + p { + "Whenever we perform an action that generates an error, we'll set that error state. We can then match on the error in a number of ways (early return, return Element, etc)." + } + CodeBlock { + contents: "
\nfn Commandline(cx: Scope) -> Element {{\n let error = use_state(cx, || None);\n\n cx.render(match *error {{\n Some(error) => rsx!(\n h1 {{ "An error occured" }}\n )\n None => rsx!(\n input {{\n oninput: move |_| error.set(Some("bad thing happened!")),\n }}\n )\n }})\n}}\n", + } + h2 { id: "passing-error-states-through-components", + Link { + to: BookRoute::BestPracticesErrorHandling { + section: BestPracticesErrorHandlingSection::PassingErrorStatesThroughComponents, + }, + class: "header", + "Passing error states through components" + } + } + p { + "If you're dealing with a handful of components with minimal nesting, you can just pass the error handle into child components." + } + CodeBlock { + contents: "
\nfn Commandline(cx: Scope) -> Element {{\n let error = use_state(cx, || None);\n\n if let Some(error) = **error {{\n return cx.render(rsx!{{ "An error occured" }});\n }}\n\n cx.render(rsx!{{\n Child {{ error: error.clone() }}\n Child {{ error: error.clone() }}\n Child {{ error: error.clone() }}\n Child {{ error: error.clone() }}\n }})\n}}\n", + } + p { + "Much like before, our child components can manually set the error during their own actions. The advantage to this pattern is that we can easily isolate error states to a few components at a time, making our app more predictable and robust." + } + h2 { id: "going-global", + Link { + to: BookRoute::BestPracticesErrorHandling { + section: BestPracticesErrorHandlingSection::GoingGlobal, + }, + class: "header", + "Going global" + } + } + p { + "A strategy for handling cascaded errors in larger apps is through signaling an error using global state. This particular pattern involves creating an \"error\" context, and then setting it wherever relevant. This particular method is not as \"sophisticated\" as React's error boundary, but it is more fitting for Rust." + } + p { + "To get started, consider using a built-in hook like " + code { "use_context" } + " and " + code { "use_context_provider" } + " or Fermi. Of course, it's pretty easy to roll your own hook too." + } + p { + "At the \"top\" of our architecture, we're going to want to explicitly declare a value that could be an error." + } + CodeBlock { contents: "
\nenum InputError {{\n None,\n TooLong,\n TooShort,\n}}\n\nstatic INPUT_ERROR: Atom<InputError> = |_| InputError::None;\n" } + p { + "Then, in our top level component, we want to explicitly handle the possible error state for this part of the tree." + } + CodeBlock { + contents: "
\nfn TopLevel(cx: Scope) -> Element {{\n let error = use_read(cx, INPUT_ERROR);\n\n match error {{\n TooLong => return cx.render(rsx!{{ "FAILED: Too long!" }}),\n TooShort => return cx.render(rsx!{{ "FAILED: Too Short!" }}),\n _ => {{}}\n }}\n}}\n", + } + p { + "Now, whenever a downstream component has an error in its actions, it can simply just set its own error state:" + } + CodeBlock { + contents: "
\nfn Commandline(cx: Scope) -> Element {{\n let set_error = use_set(cx, INPUT_ERROR);\n\n cx.render(rsx!{{\n input {{\n oninput: move |evt| {{\n if evt.value.len() > 20 {{\n set_error(InputError::TooLong);\n }}\n }}\n }}\n }})\n}}\n", + } + p { + "This approach to error handling is best in apps that have \"well defined\" error states. Consider using a crate like " + code { "thiserror" } + " or " + code { "anyhow" } + " to simplify the generation of the error types." + } + p { + "This pattern is widely popular in many contexts and is particularly helpful whenever your code generates a non-recoverable error. You can gracefully capture these \"global\" error states without panicking or mucking up state." + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum BestPracticesAntipatternsSection { + #[default] + Empty, + Antipatterns, + UnnecessarilyNestedFragments, + IncorrectIteratorKeys, + AvoidInteriorMutabilityInProps, + AvoidUpdatingStateDuringRender, +} +impl std::str::FromStr for BestPracticesAntipatternsSection { + type Err = BestPracticesAntipatternsSectionParseError; + fn from_str(s: &str) -> Result
\n// ❌ Don't unnecessarily nest fragments\nlet _ = cx.render(rsx!(\n Fragment {{\n Fragment {{\n Fragment {{\n Fragment {{\n Fragment {{\n div {{ "Finally have a real node!" }}\n }}\n }}\n }}\n }}\n }}\n));\n\n// ✅ Render shallow structures\ncx.render(rsx!(\n div {{ "Finally have a real node!" }}\n))\n", + name: "anti_patterns.rs".to_string(), + } + h2 { id: "incorrect-iterator-keys", + Link { + to: BookRoute::BestPracticesAntipatterns { + section: BestPracticesAntipatternsSection::IncorrectIteratorKeys, + }, + class: "header", + "Incorrect Iterator Keys" + } + } + p { + "As described in the " + Link { + to: BookRoute::InteractivityDynamicRendering { + section: InteractivityDynamicRenderingSection::TheKeyAttribute, + }, + "dynamic rendering chapter" + } + ", list items must have unique keys that are associated with the same items across renders. This helps Dioxus associate state with the contained components and ensures good diffing performance. Do not omit keys, unless you know that the list will never change." + } + CodeBlock { + contents: "
\nlet data: &HashMap<_, _> = &cx.props.data;\n\n// ❌ No keys\ncx.render(rsx! {{\n ul {{\n data.values().map(|value| rsx!(\n li {{ "List item: {{value}}" }}\n ))\n }}\n}});\n\n// ❌ Using index as keys\ncx.render(rsx! {{\n ul {{\n cx.props.data.values().enumerate().map(|(index, value)| rsx!(\n li {{ key: "{{index}}", "List item: {{value}}" }}\n ))\n }}\n}});\n\n// ✅ Using unique IDs as keys:\ncx.render(rsx! {{\n ul {{\n cx.props.data.iter().map(|(key, value)| rsx!(\n li {{ key: "{{key}}", "List item: {{value}}" }}\n ))\n }}\n}})\n", + name: "anti_patterns.rs".to_string(), + } + h2 { id: "avoid-interior-mutability-in-props", + Link { + to: BookRoute::BestPracticesAntipatterns { + section: BestPracticesAntipatternsSection::AvoidInteriorMutabilityInProps, + }, + class: "header", + "Avoid Interior Mutability in Props" + } + } + p { + "While it is technically acceptable to have a " + code { "Mutex" } + " or a " + code { "RwLock" } + " in the props, they will be difficult to use." + } + p { + "Suppose you have a struct " + code { "User" } + " containing the field " + code { "username: String" } + ". If you pass a " + code { "Mutex
\n[package]\nname = "example"\n# ...other fields...\n\n[package.metadata.bundle]\nname = "DogSearch"\nidentifier = "com.dogs.dogsearch"\nversion = "1.0.0"\ncopyright = "Copyright (c) Jane Doe 2016. All rights reserved."\ncategory = "Developer Tool"\nshort_description = "Easily search for Dog photos"\nlong_description = """\nThis app makes it quick and easy to browse photos of dogs from over 200 bree\n"""\n", + } + h2 { id: "building", + Link { + to: BookRoute::PublishingDesktop { + section: PublishingDesktopSection::Building, + }, + class: "header", + "Building" + } + } + p { + "Following cargo-bundle's instructions, we simply " + code { "cargo-bundle --release" } + " to produce a final app with all the optimizations and assets builtin." + } + p { + "Once you've ran " + code { "cargo-bundle --release" } + ", your app should be accessible in" + } + p { + code { "target/release/bundle/
\nenum Mutation {{\n AppendChildren,\n AssignId,\n CreatePlaceholder,\n CreateTextNode,\n HydrateText,\n LoadTemplate,\n ReplaceWith,\n ReplacePlaceholder,\n InsertAfter,\n InsertBefore,\n SetAttribute,\n SetText,\n NewEventListener,\n RemoveEventListener,\n Remove,\n PushRoot,\n}}\n", + } + p { + "The Dioxus diffing mechanism operates as a " + Link { to: "https://en.wikipedia.org/wiki/Stack_machine", "stack machine" } + " where the \"push_root\" method pushes a new \"real\" DOM node onto the stack and \"append_child\" and \"replace_with\" both remove nodes from the stack." + } + h3 { id: "an-example", + Link { + to: BookRoute::CustomRendererIndex { + section: CustomRendererIndexSection::AnExample, + }, + class: "header", + "An Example" + } + } + p { + "For the sake of understanding, let's consider this example – a very simple UI declaration:" + } + CodeBlock { contents: "
\nrsx!( h1 {{"count {{x}}"}} )\n" } + p { + "To get things started, Dioxus must first navigate to the container of this h1 tag. To \"navigate\" here, the internal diffing algorithm generates the DomEdit " + code { "PushRoot" } + " where the ID of the root is the container." + } + p { + "When the renderer receives this instruction, it pushes the actual Node onto its own stack. The real renderer's stack will look like this:" + } + CodeBlock { contents: "
\ninstructions: [\n PushRoot(Container)\n]\nstack: [\n ContainerNode,\n]\n" } + p { + "Next, Dioxus will encounter the h1 node. The diff algorithm decides that this node needs to be created, so Dioxus will generate the DomEdit " + code { "CreateElement" } + ". When the renderer receives this instruction, it will create an unmounted node and push it into its own stack:" + } + CodeBlock { contents: "
\ninstructions: [\n PushRoot(Container),\n CreateElement(h1),\n]\nstack: [\n ContainerNode,\n h1,\n]\n" } + p { + "Next, Dioxus sees the text node, and generates the " + code { "CreateTextNode" } + " DomEdit:" + } + CodeBlock { contents: "
\ninstructions: [\n PushRoot(Container),\n CreateElement(h1),\n CreateTextNode("hello world")\n]\nstack: [\n ContainerNode,\n h1,\n "hello world"\n]\n" } + p { + "Remember, the text node is not attached to anything (it is unmounted) so Dioxus needs to generate an Edit that connects the text node to the h1 element. It depends on the situation, but in this case, we use " + code { "AppendChildren" } + ". This pops the text node off the stack, leaving the h1 element as the next element in line." + } + CodeBlock { contents: "
\ninstructions: [\n PushRoot(Container),\n CreateElement(h1),\n CreateTextNode("hello world"),\n AppendChildren(1)\n]\nstack: [\n ContainerNode,\n h1\n]\n" } + p { + "We call " + code { "AppendChildren" } + " again, popping off the h1 node and attaching it to the parent:" + } + CodeBlock { contents: "
\ninstructions: [\n PushRoot(Container),\n CreateElement(h1),\n CreateTextNode("hello world"),\n AppendChildren(1),\n AppendChildren(1)\n]\nstack: [\n ContainerNode,\n]\n" } + p { "Finally, the container is popped since we don't need it anymore." } + CodeBlock { contents: "
\ninstructions: [\n PushRoot(Container),\n CreateElement(h1),\n CreateTextNode("hello world"),\n AppendChildren(1),\n AppendChildren(1),\n PopRoot\n]\nstack: []\n" } + p { "Over time, our stack looked like this:" } + CodeBlock { contents: "
\n[]\n[Container]\n[Container, h1]\n[Container, h1, "hello world"]\n[Container, h1]\n[Container]\n[]\n" } + p { + "Notice how our stack is empty once UI has been mounted. Conveniently, this approach completely separates the Virtual DOM and the Real DOM. Additionally, these edits are serializable, meaning we can even manage UIs across a network connection. This little stack machine and serialized edits make Dioxus independent of platform specifics." + } + p { + "Dioxus is also really fast. Because Dioxus splits the diff and patch phase, it's able to make all the edits to the RealDOM in a very short amount of time (less than a single frame) making rendering very snappy. It also allows Dioxus to cancel large diffing operations if higher priority work comes in while it's diffing." + } + p { + "It's important to note that there " + em { "is" } + " one layer of connectedness between Dioxus and the renderer. Dioxus saves and loads elements (the PushRoot edit) with an ID. Inside the VirtualDOM, this is just tracked as a u64." + } + p { + "Whenever a " + code { "CreateElement" } + " edit is generated during diffing, Dioxus increments its node counter and assigns that new element its current NodeCount. The RealDom is responsible for remembering this ID and pushing the correct node when PushRoot(ID) is generated. Dioxus reclaims the IDs of elements when removed. To stay in sync with Dioxus you can use a sparse Vec (Vec" + " " + "<" + " " + "Option" + p { class: "inline-html-block", dangerous_inner_html: "
\npub async fn run(&mut self) -> dioxus_core::error::Result<()> {{\n // Push the body element onto the WebsysDom's stack machine\n let mut websys_dom = crate::new::WebsysDom::new(prepare_websys_dom());\n websys_dom.stack.push(root_node);\n\n // Rebuild or hydrate the virtualdom\n let mutations = self.internal_dom.rebuild();\n websys_dom.apply_mutations(mutations);\n\n // Wait for updates from the real dom and progress the virtual dom\n loop {{\n let user_input_future = websys_dom.wait_for_event();\n let internal_event_future = self.internal_dom.wait_for_work();\n\n match select(user_input_future, internal_event_future).await {{\n Either::Left((_, _)) => {{\n let mutations = self.internal_dom.work_with_deadline(|| false);\n websys_dom.apply_mutations(mutations);\n }},\n Either::Right((event, _)) => websys_dom.handle_event(event),\n }}\n\n // render\n }}\n}}\n", + } + p { + "It's important that you decode the real events from your event system into Dioxus' synthetic event system (synthetic meaning abstracted). This simply means matching your event type and creating a Dioxus " + code { "UserEvent" } + " type. Right now, the VirtualEvent system is modeled almost entirely around the HTML spec, but we are interested in slimming it down." + } + CodeBlock { + contents: "
\nfn virtual_event_from_websys_event(event: &web_sys::Event) -> VirtualEvent {{\n match event.type_().as_str() {{\n "keydown" => {{\n let event: web_sys::KeyboardEvent = event.clone().dyn_into().unwrap();\n UserEvent::KeyboardEvent(UserEvent {{\n scope_id: None,\n priority: EventPriority::Medium,\n name: "keydown",\n // This should be whatever element is focused\n element: Some(ElementId(0)),\n data: Arc::new(KeyboardData{{\n char_code: event.char_code(),\n key: event.key(),\n key_code: event.key_code(),\n alt_key: event.alt_key(),\n ctrl_key: event.ctrl_key(),\n meta_key: event.meta_key(),\n shift_key: event.shift_key(),\n location: event.location(),\n repeat: event.repeat(),\n which: event.which(),\n }})\n }})\n }}\n _ => todo!()\n }}\n}}\n", + } + h2 { id: "custom-raw-elements", + Link { + to: BookRoute::CustomRendererIndex { + section: CustomRendererIndexSection::CustomRawElements, + }, + class: "header", + "Custom raw elements" + } + } + p { + "If you need to go as far as relying on custom elements for your renderer – you totally can. This still enables you to use Dioxus' reactive nature, component system, shared state, and other features, but will ultimately generate different nodes. All attributes and listeners for the HTML and SVG namespace are shuttled through helper structs that essentially compile away (pose no runtime overhead). You can drop in your own elements any time you want, with little hassle. However, you must be absolutely sure your renderer can handle the new type, or it will crash and burn." + } + p { "These custom elements are defined as unit structs with trait implementations." } + p { + "For example, the " + code { "div" } + " element is (approximately!) defined as such:" + } + CodeBlock { + contents: "
\nstruct div;\nimpl div {{\n /// Some glorious documentation about the class property.\n const TAG_NAME: &'static str = "div";\n const NAME_SPACE: Option<&'static str> = None;\n // define the class attribute\n pub fn class<'a>(&self, cx: NodeFactory<'a>, val: Arguments) -> Attribute<'a> {{\n cx.attr("class", val, None, false)\n }}\n // more attributes\n}}\n", + } + p { + "You've probably noticed that many elements in the " + code { "rsx!" } + " macros support on-hover documentation. The approach we take to custom elements means that the unit struct is created immediately where the element is used in the macro. When the macro is expanded, the doc comments still apply to the unit struct, giving tons of in-editor feedback, even inside a proc macro." + } + h1 { id: "native-core", + Link { + to: BookRoute::CustomRendererIndex { + section: CustomRendererIndexSection::NativeCore, + }, + class: "header", + "Native Core" + } + } + p { + "If you are creating a renderer in rust, native-core provides some utilities to implement a renderer. It provides an abstraction over DomEdits and handles the layout for you." + } + h2 { id: "realdom", + Link { + to: BookRoute::CustomRendererIndex { + section: CustomRendererIndexSection::Realdom, + }, + class: "header", + "RealDom" + } + } + p { + "The " + code { "RealDom" } + " is a higher-level abstraction over updating the Dom. It updates with " + code { "DomEdits" } + " and provides a way to incrementally update the state of nodes based on what attributes change." + } + h3 { id: "example", + Link { + to: BookRoute::CustomRendererIndex { + section: CustomRendererIndexSection::Example, + }, + class: "header", + "Example" + } + } + p { + "Let's build a toy renderer with borders, size, and text color." + " " + "Before we start let's take a look at an example element we can render:" + } + CodeBlock { contents: "
\ncx.render(rsx!{{\n div{{\n color: "red",\n p{{\n border: "1px solid black",\n "hello world"\n }}\n }}\n}})\n" } + p { + "In this tree, the color depends on the parent's color. The size depends on the children's size, the current text, and the text size. The border depends on only the current node." + } + p { "In the following diagram arrows represent dataflow:" } + p { + Link { to: "https://mermaid-js.github.io/mermaid-live-editor/edit#pako:eNqdVNFqgzAU_RXJXizUUZPJmIM-jO0LukdhpCbO0JhIGteW0n9fNK1Oa0brfUnu9VxyzzkXjyCVhIIYZFzu0hwr7X2-JcIzsa3W3wqXuZdKoele22oddfa1Y0Tnfn31muvMfqeCDNq3GmvaNROmaKqZFO1DPTRhP8MOd1fTWYNDvzlmQbBMJZcq9JtjNgY1mLVUhBqQPQeojl3wGCw5PsjqnIe-zXqEL8GZ2Kz0gVMPmoeU3ND4IcuiaLGY2zRouuKncv_qGKv3VodpJe0JVU6QCQ5kgqMyWQVr8hbk4hm1PBcmsuwmnrCVH94rP7xN_ucp8sOB_EPSfz9drYVrkpc_AmH8_yTjJueUc-ntpOJkgt2os9tKjcYlt-DLUiD3UsB2KZCLcwjv3Aq33-g2v0M0xXA0MBy5DUdXi-gcJZriuLmAOSioKjAj5ld8rMsJ0DktaAJicyVYbRKQiJPBVSUx438QpqUCcYb5ls4BrrRcHUTaFizqnWGzR8W5evoFI-bJdw", + img { + src: "https://mermaid.ink/img/pako:eNqdVNFqgzAU_RXJXizUUZPJmIM-jO0LukdhpCbO0JhIGteW0n9fNK1Oa0brfUnu9VxyzzkXjyCVhIIYZFzu0hwr7X2-JcIzsa3W3wqXuZdKoele22oddfa1Y0Tnfn31muvMfqeCDNq3GmvaNROmaKqZFO1DPTRhP8MOd1fTWYNDvzlmQbBMJZcq9JtjNgY1mLVUhBqQPQeojl3wGCw5PsjqnIe-zXqEL8GZ2Kz0gVMPmoeU3ND4IcuiaLGY2zRouuKncv_qGKv3VodpJe0JVU6QCQ5kgqMyWQVr8hbk4hm1PBcmsuwmnrCVH94rP7xN_ucp8sOB_EPSfz9drYVrkpc_AmH8_yTjJueUc-ntpOJkgt2os9tKjcYlt-DLUiD3UsB2KZCLcwjv3Aq33-g2v0M0xXA0MBy5DUdXi-gcJZriuLmAOSioKjAj5ld8rMsJ0DktaAJicyVYbRKQiJPBVSUx438QpqUCcYb5ls4BrrRcHUTaFizqnWGzR8W5evoFI-bJdw", + alt: "", + title: "", + } + } + } + p { + "To help in building a Dom, native-core provides four traits: State, ChildDepState, ParentDepState, NodeDepState, and a RealDom struct. The ChildDepState, ParentDepState, and NodeDepState provide a way to describe how some information in a node relates to that of its relatives. By providing how to build a single node from its relations, native-core will derive a way to update the state of all nodes for you with " + code { "#[derive(State)]" } + ". Once you have a state you can provide it as a generic to RealDom. RealDom provides all of the methods to interact and update your new dom." + } + CodeBlock { + contents: "
\nuse dioxus_native_core::node_ref::*;\nuse dioxus_native_core::state::{{ChildDepState, NodeDepState, ParentDepState, State}};\nuse dioxus_native_core_macro::{{sorted_str_slice, State}};\n\n#[derive(Default, Copy, Clone)]\nstruct Size(f32, f32);\n// Size only depends on the current node and its children, so it implements ChildDepState\nimpl ChildDepState for Size {{\n // Size accepts a font size context\n type Ctx = f32;\n // Size depends on the Size part of each child\n type DepState = Self;\n // Size only cares about the width, height, and text parts of the current node\n const NODE_MASK: NodeMask =\n NodeMask::new_with_attrs(AttributeMask::Static(&sorted_str_slice!(["width", "height"]))).with_text();\n fn reduce<'a>(\n &mut self,\n node: NodeView,\n children: impl Iterator<Item = &'a Self::DepState>,\n ctx: &Self::Ctx,\n ) -> bool\n where\n Self::DepState: 'a,\n {{\n let mut width;\n let mut height;\n if let Some(text) = node.text() {{\n // if the node has text, use the text to size our object\n width = text.len() as f32 * ctx;\n height = *ctx;\n }} else {{\n // otherwise, the size is the maximum size of the children\n width = children\n .by_ref()\n .map(|item| item.0)\n .reduce(|accum, item| if accum >= item {{ accum }} else {{ item }})\n .unwrap_or(0.0);\n\n height = children\n .map(|item| item.1)\n .reduce(|accum, item| if accum >= item {{ accum }} else {{ item }})\n .unwrap_or(0.0);\n }}\n // if the node contains a width or height attribute it overrides the other size\n for a in node.attributes(){{\n match a.name{{\n "width" => width = a.value.as_float32().unwrap(),\n "height" => height = a.value.as_float32().unwrap(),\n // because Size only depends on the width and height, no other attributes will be passed to the member\n _ => panic!()\n }}\n }}\n // to determine what other parts of the dom need to be updated we return a boolean that marks if this member changed\n let changed = (width != self.0) || (height != self.1);\n *self = Self(width, height);\n changed\n }}\n}}\n\n#[derive(Debug, Clone, Copy, PartialEq, Default)]\nstruct TextColor {{\n r: u8,\n g: u8,\n b: u8,\n}}\n// TextColor only depends on the current node and its parent, so it implements ParentDepState\nimpl ParentDepState for TextColor {{\n type Ctx = ();\n // TextColor depends on the TextColor part of the parent\n type DepState = Self;\n // TextColor only cares about the color attribute of the current node\n const NODE_MASK: NodeMask = NodeMask::new_with_attrs(AttributeMask::Static(&["color"]));\n fn reduce(\n &mut self,\n node: NodeView,\n parent: Option<&Self::DepState>,\n _ctx: &Self::Ctx,\n ) -> bool {{\n // TextColor only depends on the color tag, so getting the first tag is equivilent to looking through all tags\n let new = match node.attributes().next().map(|attr| attr.name) {{\n // if there is a color tag, translate it\n Some("red") => TextColor {{ r: 255, g: 0, b: 0 }},\n Some("green") => TextColor {{ r: 0, g: 255, b: 0 }},\n Some("blue") => TextColor {{ r: 0, g: 0, b: 255 }},\n Some(_) => panic!("unknown color"),\n // otherwise check if the node has a parent and inherit that color\n None => match parent {{\n Some(parent) => *parent,\n None => Self::default(),\n }},\n }};\n // check if the member has changed\n let changed = new != *self;\n *self = new;\n changed\n }}\n}}\n\n#[derive(Debug, Clone, PartialEq, Default)]\nstruct Border(bool);\n// TextColor only depends on the current node, so it implements NodeDepState\nimpl NodeDepState<()> for Border {{\n type Ctx = ();\n \n // Border does not depended on any other member in the current node\n const NODE_MASK: NodeMask =\n NodeMask::new_with_attrs(AttributeMask::Static(&["border"]));\n fn reduce(&mut self, node: NodeView, _sibling: (), _ctx: &Self::Ctx) -> bool {{\n // check if the node contians a border attribute\n let new = Self(node.attributes().next().map(|a| a.name == "border").is_some());\n // check if the member has changed\n let changed = new != *self;\n *self = new;\n changed\n }}\n}}\n\n// State provides a derive macro, but anotations on the members are needed in the form #[dep_type(dep_member, CtxType)]\n#[derive(State, Default, Clone)]\nstruct ToyState {{\n // the color member of it's parent and no context\n #[parent_dep_state(color)]\n color: TextColor,\n // depends on the node, and no context\n #[node_dep_state()]\n border: Border,\n // depends on the layout_width member of children and f32 context (for text size)\n #[child_dep_state(size, f32)]\n size: Size,\n}}\n", + } + p { + "Now that we have our state, we can put it to use in our dom. Re can update the dom with update_state to update the structure of the dom (adding, removing, and changing properties of nodes) and then apply_mutations to update the ToyState for each of the nodes that changed." + } + CodeBlock { + contents: "
\nfn main(){{\n fn app(cx: Scope) -> Element {{\n cx.render(rsx!{{\n div{{\n color: "red",\n "hello world"\n }}\n }})\n }}\n let vdom = VirtualDom::new(app);\n let rdom: RealDom<ToyState> = RealDom::new();\n\n let mutations = dom.rebuild();\n // update the structure of the real_dom tree\n let to_update = rdom.apply_mutations(vec![mutations]);\n let mut ctx = AnyMap::new();\n // set the font size to 3.3\n ctx.insert(3.3f32);\n // update the ToyState for nodes in the real_dom tree\n let _to_rerender = rdom.update_state(&dom, to_update, ctx).unwrap();\n\n // we need to run the vdom in a async runtime\n tokio::runtime::Builder::new_current_thread()\n .enable_all()\n .build()?\n .block_on(async {{\n loop{{\n let wait = vdom.wait_for_work();\n let mutations = vdom.work_with_deadline(|| false);\n let to_update = rdom.apply_mutations(mutations);\n let mut ctx = AnyMap::new();\n ctx.insert(3.3);\n let _to_rerender = rdom.update_state(vdom, to_update, ctx).unwrap();\n\n // render...\n }}\n }})\n}}\n", + } + h2 { id: "layout", + Link { + to: BookRoute::CustomRendererIndex { + section: CustomRendererIndexSection::Layout, + }, + class: "header", + "Layout" + } + } + p { + "For most platforms, the layout of the Elements will stay the same. The layout_attributes module provides a way to apply HTML attributes to a stretch layout style." + } + h2 { id: "conclusion", + Link { + to: BookRoute::CustomRendererIndex { + section: CustomRendererIndexSection::Conclusion, + }, + class: "header", + "Conclusion" + } + } + p { + "That should be it! You should have nearly all the knowledge required on how to implement your own renderer. We're super interested in seeing Dioxus apps brought to custom desktop renderers, mobile renderers, video game UI, and even augmented reality! If you're interested in contributing to any of these projects, don't be afraid to reach out or join the " + Link { to: "https://discord.gg/XgGxMSkvUM", "community" } + "." + } + } +} +#[derive( + Clone, Copy, PartialEq, Eq, Hash, Debug, Default, serde::Serialize, serde::Deserialize, +)] +pub enum RoadmapSection { + #[default] + Empty, + RoadmapFeatureSet, + Features, + Roadmap, + Core, + Ssr, + Desktop, + Mobile, + BundlingCli, + EssentialHooks, + WorkInProgress, + BuildTool, + ServerComponentSupport, + NativeRendering, +} +impl std::str::FromStr for RoadmapSection { + type Err = RoadmapSectionParseError; + fn from_str(s: &str) -> Result
Fullstack, crossplatform,lightning fast, fully typed.
Dioxus is a Rust library for building apps that run on desktop, web, mobile, and more.
Trusted by top companies
![](\\\"static/futurewei_bw.png\\\")
![](\\\"static/airbuslogo.svg\\\")
![](\\\"static/ESA_logo.svg\\\"){kind=logo}
![](\\\"static/yclogo.svg\\\")
![](\\\"static/satellite.webp\\\")
Hello world
\"\n````\n\nBoth of those commands will output the following RSX:\n\n````rs\ndiv { \"Hello world\" }\n````\n\nThe `dx translate` command will output the RSX to stdout. You can use the `--output` flag to write the RSX to a file instead.\n\n````sh\ndx translate --raw \"Hello world
\" --output index.rs\n````\n\nYou can automatically create a component with the `--component` flag.\n\n````sh\ndx translate --raw \"Hello world
\" --component\n````\n\nThis will output the following component:\n\n````rs\nfn component(cx: Scope) -> Element {\n cx.render(rsx! {\n div { \"Hello world\" }\n })\n}\n````\n\nTo learn more about the different flags `dx translate` supports, run `dx translate --help`."
+ }
+ 34usize => {
+ "# Middleware\n\nExtractors allow you to wrap your server function in some code that changes either the request or the response. Dioxus fullstack integrates with [Tower](https://docs.rs/tower/latest/tower/index.html) to allow you to wrap your server functions in middleware.\n\nYou can use the `#[middleware]` attribute to add a layer of middleware to your server function. Let's add a timeout middleware to a server function. This middleware will stop running the server function if it reaches a certain timeout:\n\n````rust@server_function_middleware.rs\n#[server]\n// Add a timeout middleware to the server function that will return an error if the function takes longer than 1 second to execute\n#[middleware(tower_http::timeout::TimeoutLayer::new(std::time::Duration::from_secs(1)))]\npub async fn timeout() -> Result<(), ServerFnError> {\n tokio::time::sleep(std::time::Duration::from_secs(2)).await;\n Ok(())\n}\n````"
+ }
+ 69usize => {
+ "# Introduction\n\nThe ✨**Dioxus CLI**✨ is a tool to get Dioxus projects off the ground.\n\nThere's no documentation for commands here, but you can see all commands using `dx --help` once you've installed the CLI! Furthermore, you can run `dx Index
\n\n````\n\n## Layouts with dynamic segments\n\nYou can combine layouts with [nested routes](./routes/nested.md) to create dynamic layouts with content that changes based on the current route.\n\nJust like routes, layouts components must accept a prop for each dynamic segment in the route. For example, if you have a route with a dynamic segment like `/:name`, your layout component must accept a `name` prop:\n\n````rust@outlet.rs\n#[derive(Routable, Clone)]\n#[rustfmt::skip]\nenum Route {\n #[nest(\"/:name\")]\n #[layout(Wrapper)]\n #[route(\"/\")]\n Index {\n name: String,\n },\n}\n\n#[component]\nfn Wrapper(cx: Scope, name: String) -> Element {\n render! {\n header { \"Welcome {name}!\" }\n // The index route will be rendered here\n Outlet::\"\"
\n````\n\n#### Applying Mutations\n\nAfter the renderer has created all of the new templates, it can begin to process the mutations.\n\nWhen the renderer starts, it should contain the Root node on the stack and store the Root node with an id of 0. The Root node is the top-level node of the UI. In HTML, this is the `` element.\n\n````rust\ninstructions: []\nstack: [\n\tRootNode,\n]\nnodes: [\n\tRootNode,\n]\n````\n\nThe first mutation is a `LoadTemplate` mutation. This tells the renderer to load a root from the template with the given id. The renderer will then push the root node of the template onto the stack and store it with an id for later. In this case, the root node is an h1 element.\n\n````rust\ninstructions: [\n\tLoadTemplate {\n\t\t// the id of the template\n\t\tname: \"main.rs:1:1:0\",\n\t\t// the index of the root node in the template\n\t\tindex: 0,\n\t\t// the id to store\n\t\tid: ElementId(1),\n\t}\n]\nstack: [\n\tRootNode,\n\t