Mirrors/dioxus
2
0
Fork 0
mirror of https://github.com/DioxusLabs/dioxus synced 2024-12-03 17:39:11 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'master' into fix-docs-rs-desktop-build

Browse source
This commit is contained in:
Jonathan Kelley 2023-09-16 11:54:08 -07:00 committed by GitHub
commit e4620250bd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
420 changed files with 2207 additions and 13868 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/cli_release.yml vendored
View file

@ -29,7 +29,7 @@ jobs:
toolchain: "1.70.0",
}
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Install stable
uses: dtolnay/rust-toolchain@master
with:

2
.github/workflows/docs stable.yml vendored
View file

@ -23,7 +23,7 @@ jobs:
- name: Setup mdBook
run: |
cargo install mdbook --git https://github.com/Demonthos/mdBook.git --branch master
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Build
run: cd docs &&

15
.github/workflows/docs.yml vendored
View file

@ -1,12 +1,13 @@
name: github pages
on:
push:
paths:
- docs/**
- .github/workflows/docs.yml
branches:
- master
workflow_dispatch:
# push:
# paths:
# - docs/**
# - .github/workflows/docs.yml
# branches:
# - master
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@ -28,7 +29,7 @@ jobs:
- name: Setup mdBook
run: |
cargo install mdbook --git https://github.com/Demonthos/mdBook.git --branch master
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Build
run: cd docs &&

58
.github/workflows/main.yml vendored
View file

@ -41,7 +41,7 @@ jobs:
- uses: Swatinem/rust-cache@v2
- run: sudo apt-get update
- run: sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- run: cargo check --all --examples --tests
test:
@ -56,7 +56,7 @@ jobs:
- uses: davidB/rust-cargo-make@v1
- uses: browser-actions/setup-firefox@latest
- uses: jetli/wasm-pack-action@v0.4.0
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- run: cargo make tests
fmt:
@ -67,7 +67,7 @@ jobs:
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- run: rustup component add rustfmt
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- run: cargo fmt --all -- --check
clippy:
@ -80,57 +80,61 @@ jobs:
- run: sudo apt-get update
- run: sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev
- run: rustup component add clippy
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- run: cargo clippy --workspace --examples --tests -- -D warnings
matrix_test:
runs-on: ${{ matrix.platform.os }}
env:
RUST_CARGO_COMMAND: ${{ matrix.platform.cross == true && 'cross' || 'cargo' }}
strategy:
matrix:
platform:
- {
target: x86_64-pc-windows-msvc,
os: windows-latest,
toolchain: '1.70.0',
toolchain: "1.70.0",
cross: false,
command: 'test',
args: '--all --tests'
command: "test",
args: "--all --tests",
}
- {
target: x86_64-apple-darwin,
os: macos-latest,
toolchain: '1.70.0',
toolchain: "1.70.0",
cross: false,
command: 'test',
args: '--all --tests'
command: "test",
args: "--all --tests",
}
- {
target: aarch64-apple-ios,
os: macos-latest,
toolchain: '1.70.0',
toolchain: "1.70.0",
cross: false,
command: 'build',
args: '--package dioxus-mobile'
command: "build",
args: "--package dioxus-mobile",
}
- {
target: aarch64-linux-android,
os: ubuntu-latest,
toolchain: '1.70.0',
toolchain: "1.70.0",
cross: true,
command: 'build',
args: '--package dioxus-mobile'
command: "build",
args: "--package dioxus-mobile",
}
steps:
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: install stable
uses: actions-rs/toolchain@v1
uses: dtolnay/rust-toolchain@master
with:
toolchain: ${{ matrix.platform.toolchain }}
target: ${{ matrix.platform.target }}
override: true
default: true
targets: ${{ matrix.platform.target }}
- name: Install cross
if: ${{ matrix.platform.cross == true }}
uses: taiki-e/install-action@cross
- uses: Swatinem/rust-cache@v2
with:
@ -138,13 +142,8 @@ jobs:
save-if: ${{ matrix.features.key == 'all' }}
- name: test
uses: actions-rs/cargo@v1
with:
use-cross: ${{ matrix.platform.cross }}
command: ${{ matrix.platform.command }}
args: --target ${{ matrix.platform.target }} ${{ matrix.platform.args }}
run: |
${{ env.RUST_CARGO_COMMAND }} ${{ matrix.platform.command }} ${{ matrix.platform.args }} --target ${{ matrix.platform.target }}
# Coverage is disabled until we can fix it
# coverage:
@ -155,7 +154,7 @@ jobs:
# options: --security-opt seccomp=unconfined
# steps:
# - name: Checkout repository
# uses: actions/checkout@v3
# uses: actions/checkout@v4
# - name: Generate code coverage
# run: |
# apt-get update &&\
@ -166,4 +165,3 @@ jobs:
# uses: codecov/codecov-action@v2
# with:
# fail_ci_if_error: false

2
.github/workflows/miri.yml vendored
View file

@ -69,7 +69,7 @@ jobs:
if: runner.os == 'Linux'
run: echo "MIRIFLAGS=-Zmiri-tag-gc=1" >> $GITHUB_ENV
- uses: actions/checkout@v3
- uses: actions/checkout@v4
- name: Install Rust ${{ env.rust_nightly }}
uses: dtolnay/rust-toolchain@master
with:

71
.github/workflows/playwright.yml vendored
View file

@ -1,9 +1,9 @@
name: Playwright Tests
on:
push:
branches: [ main, master ]
branches: [main, master]
pull_request:
branches: [ main, master ]
branches: [main, master]
defaults:
run:
working-directory: ./playwright-tests
@ -16,39 +16,36 @@ jobs:
test:
if: github.event.pull_request.draft == false
timeout-minutes: 60
runs-on: ubuntu-20.04
runs-on: ubuntu-latest
steps:
# Do our best to cache the toolchain and node install steps
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 16
- name: Install Rust
uses: actions-rs/toolchain@v1
with:
profile: minimal
toolchain: stable
override: true
- uses: Swatinem/rust-cache@v2
- name: Install WASM toolchain
run: rustup target add wasm32-unknown-unknown
- name: Install dependencies
run: npm ci
- name: Install Playwright
run: npm install -D @playwright/test
- name: Install Playwright Browsers
run: npx playwright install --with-deps
# Cache the CLI by using cargo run internally
# - name: Install Dioxus CLI
# uses: actions-rs/cargo@v1
# with:
# command: install
# args: --path packages/cli
- name: Run Playwright tests
run: npx playwright test
- uses: actions/upload-artifact@v3
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30
# Do our best to cache the toolchain and node install steps
- uses: actions/checkout@v4
- uses: actions/setup-node@v3
with:
node-version: 16
- name: Install Rust
uses: dtolnay/rust-toolchain@master
with:
toolchain: stable
targets: x86_64-unknown-linux-gnu,wasm32-unknown-unknown
- uses: Swatinem/rust-cache@v2
- name: Install dependencies
run: npm ci
- name: Install Playwright
run: npm install -D @playwright/test
- name: Install Playwright Browsers
run: npx playwright install --with-deps
# Cache the CLI by using cargo run internally
# - name: Install Dioxus CLI
# uses: actions-rs/cargo@v1
# with:
# command: install
# args: --path packages/cli
- name: Run Playwright tests
run: npx playwright test
- uses: actions/upload-artifact@v3
if: always()
with:
name: playwright-report
path: playwright-report/
retention-days: 30

10
Cargo.toml
View file

@ -37,11 +37,10 @@ members = [
"packages/fullstack/examples/salvo-hello-world",
"packages/fullstack/examples/warp-hello-world",
"packages/fullstack/examples/static-hydrated",
"docs/guide",
"docs/router",
# Full project examples
"examples/tailwind",
"examples/PWA-example",
"examples/query_segments_demo",
# Playwright tests
"playwright-tests/liveview",
"playwright-tests/web",
@ -50,12 +49,12 @@ members = [
exclude = ["examples/mobile_demo"]
[workspace.package]
version = "0.4.1"
version = "0.4.2"
# dependencies that are shared across packages
[workspace.dependencies]
dioxus = { path = "packages/dioxus", version = "0.4.0" }
dioxus-core = { path = "packages/core", version = "0.4.1" }
dioxus-core = { path = "packages/core", version = "0.4.2" }
dioxus-core-macro = { path = "packages/core-macro", version = "0.4.0" }
dioxus-router = { path = "packages/router", version = "0.4.1" }
dioxus-router-macro = { path = "packages/router-macro", version = "0.4.1" }
@ -81,7 +80,8 @@ generational-box = { path = "packages/generational-box" }
dioxus-hot-reload = { path = "packages/hot-reload", version = "0.4.0" }
dioxus-fullstack = { path = "packages/fullstack", version = "0.4.1" }
dioxus_server_macro = { path = "packages/server-macro", version = "0.4.1" }
log = "0.4.19"
tracing = "0.1.37"
tracing-futures = "0.2.5"
tokio = "1.28"
slab = "0.4.2"
futures-channel = "0.3.21"

0
docs/.nojekyll
View file

19
docs/README.md
View file

@ -1,19 +0,0 @@
# Building the Documentation
Dioxus uses a fork of MdBook with multilanguage support. To build the documentation, you will need to install the forked version of MdBook.
```sh
cargo install mdbook --git https://github.com/Demonthos/mdBook.git --branch master
```
Then, you can build the documentation by running:
```sh
cd docs
cd guide
mdbook build -d ../nightly/guide
cd ..
cd router
mdbook build -d ../nightly/router
cd ../../
```

1
docs/fermi/.gitignore vendored
View file

@ -1 +0,0 @@
book

6
docs/fermi/book.toml
View file

@ -1,6 +0,0 @@
[book]
authors = ["Jonathan Kelley"]
language = "en"
multilingual = false
src = "src"
title = "Fermi Guide"

3
docs/fermi/src/SUMMARY.md
View file

@ -1,3 +0,0 @@
# Summary
- [Chapter 1](./chapter_1.md)

1
docs/fermi/src/chapter_1.md
View file

@ -1 +0,0 @@
# Chapter 1

1
docs/guide/.gitignore vendored
View file

@ -1 +0,0 @@
book/

27
docs/guide/Cargo.toml
View file

@ -1,27 +0,0 @@
[package]
name = "dioxus-guide"
version = "0.0.1"
edition = "2021"
description = "Dioxus guide, including testable examples"
license = "MIT OR Apache-2.0"
publish = false
[dev-dependencies]
dioxus = { path = "../../packages/dioxus" }
dioxus-desktop = { path = "../../packages/desktop" }
dioxus-web = { path = "../../packages/web" }
dioxus-ssr = { path = "../../packages/ssr" }
dioxus-native-core = { path = "../../packages/native-core" }
dioxus-native-core-macro = { path = "../../packages/native-core-macro" }
dioxus-router = { path = "../../packages/router" }
dioxus-liveview = { path = "../../packages/liveview", features = ["axum"] }
dioxus-tui = { path = "../../packages/dioxus-tui" }
dioxus-fullstack = { path = "../../packages/fullstack" }
# dioxus = { path = "../../packages/dioxus", features = ["desktop", "web", "ssr", "router", "fermi", "tui"] }
fermi = { path = "../../packages/fermi" }
shipyard = "0.6.2"
serde = { version = "1.0.138", features=["derive"] }
reqwest = { version = "0.11.11", features = ["json"] }
tokio = { version = "1.19.2", features = ["full"] }
axum = { version = "0.6.1", features = ["ws"] }
gloo-storage = "0.2.2"

40
docs/guide/book.toml
View file

@ -1,40 +0,0 @@
[book.en]
title = "Dioxus Documentation"
description = "Get started with Dioxus, a portable, performant, and ergonomic framework for building cross-platform user interfaces in Rust"
authors = ["Jonathan Kelley"]
language = "en"
[language.en]
name = "English"
[language.pt-br]
name = "Português Brasileiro"
title = "Documentação do Dioxus"
description = "Introdução ao Dioxus, um framework portátil, de alto desempenho e ergonômico para criar interfaces de usuário multiplataforma em Rust."
[rust]
edition = "2018"
[output.html]
mathjax-support = true
site-url = "/mdBook/"
git-repository-url = "https://github.com/DioxusLabs/dioxus/edit/master/docs/guide"
edit-url-template = "https://github.com/DioxusLabs/dioxus/edit/master/docs/guide/{path}"
[output.html.playground]
editable = true
line-numbers = true
# running examples will not work because dioxus is not a included in the playground
runnable = false
[output.html.search]
limit-results = 20
use-boolean-and = true
boost-title = 2
boost-hierarchy = 2
boost-paragraph = 1
expand = true
heading-split-level = 2
# [output.html.redirect]
# "/format/config.html" = "configuration/index.html"

1
docs/guide/examples/Readme.md
View file

@ -1 +0,0 @@
Some of these examples (e.g. web) cannot be run. The code samples are here mostly so that we can easily check that they compile using `cargo test`.

71
docs/guide/examples/anti_patterns.rs
View file

@ -1,71 +0,0 @@
#![allow(non_snake_case, unused)]
//! This example shows what *not* to do
use std::collections::HashMap;
use dioxus::prelude::*;
fn main() {}
fn AntipatternNestedFragments(cx: Scope<()>) -> Element {
// ANCHOR: nested_fragments
// ❌ Don't unnecessarily nest fragments
let _ = cx.render(rsx!(
Fragment {
Fragment {
Fragment {
Fragment {
Fragment {
div { "Finally have a real node!" }
}
}
}
}
}
));
// ✅ Render shallow structures
cx.render(rsx!(
div { "Finally have a real node!" }
))
// ANCHOR_END: nested_fragments
}
#[derive(PartialEq, Props)]
struct NoKeysProps {
data: HashMap<u32, String>,
}
fn AntipatternNoKeys(cx: Scope<NoKeysProps>) -> Element {
// ANCHOR: iter_keys
let data: &HashMap<_, _> = &cx.props.data;
// ❌ No keys
cx.render(rsx! {
ul {
data.values().map(|value| rsx!(
li { "List item: {value}" }
))
}
});
// ❌ Using index as keys
cx.render(rsx! {
ul {
cx.props.data.values().enumerate().map(|(index, value)| rsx!(
li { key: "{index}", "List item: {value}" }
))
}
});
// ✅ Using unique IDs as keys:
cx.render(rsx! {
ul {
cx.props.data.iter().map(|(key, value)| rsx!(
li { key: "{key}", "List item: {value}" }
))
}
})
// ANCHOR_END: iter_keys
}

18
docs/guide/examples/boolean_attribute.rs
View file

@ -1,18 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
// ANCHOR: boolean_attribute
cx.render(rsx! {
div {
hidden: "false",
"hello"
}
})
// ANCHOR_END: boolean_attribute
}

27
docs/guide/examples/component_borrowed_props.rs
View file

@ -1,27 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: App
fn App(cx: Scope) -> Element {
let hello = "Hello Dioxus!";
cx.render(rsx!(TitleCard { title: hello }))
}
// ANCHOR_END: App
// ANCHOR: TitleCard
#[derive(Props)]
struct TitleCardProps<'a> {
title: &'a str,
}
fn TitleCard<'a>(cx: Scope<'a, TitleCardProps<'a>>) -> Element {
cx.render(rsx! {
h1 { "{cx.props.title}" }
})
}
// ANCHOR_END: TitleCard

36
docs/guide/examples/component_children.rs
View file

@ -1,36 +0,0 @@
// ANCHOR: all
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
fn App(cx: Scope) -> Element {
// ANCHOR: Clickable_usage
cx.render(rsx! {
Clickable {
href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",
"How to " i {"not"} " be seen"
}
})
// ANCHOR_END: Clickable_usage
}
// ANCHOR: Clickable
#[derive(Props)]
struct ClickableProps<'a> {
href: &'a str,
children: Element<'a>,
}
fn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {
cx.render(rsx!(
a {
href: "{cx.props.href}",
class: "fancy-button",
&cx.props.children
}
))
}
// ANCHOR_END: Clickable

37
docs/guide/examples/component_children_inspect.rs
View file

@ -1,37 +0,0 @@
// ANCHOR: all
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
fn App(cx: Scope) -> Element {
// ANCHOR: Clickable_usage
cx.render(rsx! {
Clickable {
href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",
"How to " i {"not"} " be seen"
}
})
// ANCHOR_END: Clickable_usage
}
#[derive(Props)]
struct ClickableProps<'a> {
href: &'a str,
children: Element<'a>,
}
// ANCHOR: Clickable
fn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {
match cx.props.children {
Some(VNode { dynamic_nodes, .. }) => {
todo!("render some stuff")
}
_ => {
todo!("render some other stuff")
}
}
}
// ANCHOR_END: Clickable

36
docs/guide/examples/component_element_props.rs
View file

@ -1,36 +0,0 @@
// ANCHOR: all
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
fn App(cx: Scope) -> Element {
// ANCHOR: Clickable_usage
cx.render(rsx! {
Clickable {
href: "https://www.youtube.com/watch?v=C-M2hs3sXGo",
body: cx.render(rsx!("How to " i {"not"} " be seen")),
}
})
// ANCHOR_END: Clickable_usage
}
// ANCHOR: Clickable
#[derive(Props)]
struct ClickableProps<'a> {
href: &'a str,
body: Element<'a>,
}
fn Clickable<'a>(cx: Scope<'a, ClickableProps<'a>>) -> Element {
cx.render(rsx!(
a {
href: "{cx.props.href}",
class: "fancy-button",
&cx.props.body
}
))
}
// ANCHOR_END: Clickable

34
docs/guide/examples/component_owned_props.rs
View file

@ -1,34 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: App
fn App(cx: Scope) -> Element {
cx.render(rsx! {
Likes {
score: 42,
},
})
}
// ANCHOR_END: App
// ANCHOR: Likes
// Remember: Owned props must implement `PartialEq`!
#[derive(PartialEq, Props)]
struct LikesProps {
score: i32,
}
fn Likes(cx: Scope<LikesProps>) -> Element {
cx.render(rsx! {
div {
"This post has ",
b { "{cx.props.score}" },
" likes"
}
})
}
// ANCHOR_END: Likes

110
docs/guide/examples/component_props_options.rs
View file

@ -1,110 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
cx.render(rsx! {
// ANCHOR: OptionalProps_usage
Title {
title: "Some Title",
},
Title {
title: "Some Title",
subtitle: "Some Subtitle",
},
// Providing an Option explicitly won't compile though:
// Title {
// title: "Some Title",
// subtitle: None,
// },
// ANCHOR_END: OptionalProps_usage
// ANCHOR: ExplicitOption_usage
ExplicitOption {
title: "Some Title",
subtitle: None,
},
ExplicitOption {
title: "Some Title",
subtitle: Some("Some Title"),
},
// This won't compile:
// ExplicitOption {
// title: "Some Title",
// },
// ANCHOR_END: ExplicitOption_usage
// ANCHOR: DefaultComponent_usage
DefaultComponent {
number: 5,
},
DefaultComponent {},
// ANCHOR_END: DefaultComponent_usage
// ANCHOR: IntoComponent_usage
IntoComponent {
string: "some &str",
},
// ANCHOR_END: IntoComponent_usage
})
}
// ANCHOR: OptionalProps
#[derive(Props)]
struct OptionalProps<'a> {
title: &'a str,
subtitle: Option<&'a str>,
}
fn Title<'a>(cx: Scope<'a, OptionalProps>) -> Element<'a> {
cx.render(rsx!(h1{
"{cx.props.title}: ",
cx.props.subtitle.unwrap_or("No subtitle provided"),
}))
}
// ANCHOR_END: OptionalProps
// ANCHOR: ExplicitOption
#[derive(Props)]
struct ExplicitOptionProps<'a> {
title: &'a str,
#[props(!optional)]
subtitle: Option<&'a str>,
}
fn ExplicitOption<'a>(cx: Scope<'a, ExplicitOptionProps>) -> Element<'a> {
cx.render(rsx!(h1 {
"{cx.props.title}: ",
cx.props.subtitle.unwrap_or("No subtitle provided"),
}))
}
// ANCHOR_END: ExplicitOption
// ANCHOR: DefaultComponent
#[derive(PartialEq, Props)]
struct DefaultProps {
// default to 42 when not provided
#[props(default = 42)]
number: i64,
}
fn DefaultComponent(cx: Scope<DefaultProps>) -> Element {
cx.render(rsx!(h1 { "{cx.props.number}" }))
}
// ANCHOR_END: DefaultComponent
// ANCHOR: IntoComponent
#[derive(PartialEq, Props)]
struct IntoProps {
#[props(into)]
string: String,
}
fn IntoComponent(cx: Scope<IntoProps>) -> Element {
cx.render(rsx!(h1 { "{cx.props.string}" }))
}
// ANCHOR_END: IntoComponent

24
docs/guide/examples/components.rs
View file

@ -1,24 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: App
fn App(cx: Scope) -> Element {
cx.render(rsx! {
About {},
About {},
})
}
// ANCHOR_END: App
// ANCHOR: About
pub fn About(cx: Scope) -> Element {
cx.render(rsx!(p {
b {"Dioxus Labs"}
" An Open Source project dedicated to making Rust UI wonderful."
}))
}
// ANCHOR_END: About

97
docs/guide/examples/conditional_rendering.rs
View file

@ -1,97 +0,0 @@
#![allow(unused)]
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
pub fn App(cx: Scope) -> Element {
let is_logged_in = use_state(cx, || false);
cx.render(rsx!(LogIn {
is_logged_in: **is_logged_in,
on_log_in: |_| is_logged_in.set(true),
on_log_out: |_| is_logged_in.set(false),
}))
}
#[inline_props]
#[rustfmt::skip]
fn LogIn<'a>(
cx: Scope<'a>,
is_logged_in: bool,
on_log_in: EventHandler<'a>,
on_log_out: EventHandler<'a>,
) -> Element<'a> {
// ANCHOR: if_else
if *is_logged_in {
cx.render(rsx! {
"Welcome!"
button {
onclick: move |_| on_log_out.call(()),
"Log Out",
}
})
} else {
cx.render(rsx! {
button {
onclick: move |_| on_log_in.call(()),
"Log In",
}
})
}
// ANCHOR_END: if_else
}
#[inline_props]
#[rustfmt::skip]
fn LogInImproved<'a>(
cx: Scope<'a>,
is_logged_in: bool,
on_log_in: EventHandler<'a>,
on_log_out: EventHandler<'a>,
) -> Element<'a> {
// ANCHOR: if_else_improved
cx.render(rsx! {
// We only render the welcome message if we are logged in
// You can use if statements in the middle of a render block to conditionally render elements
if *is_logged_in {
// Notice the body of this if statment is rsx code, not an expression
"Welcome!"
}
button {
// depending on the value of `is_logged_in`, we will call a different event handler
onclick: move |_| if *is_logged_in {
on_log_in.call(())
}
else{
on_log_out.call(())
},
if *is_logged_in {
// if we are logged in, the button should say "Log Out"
"Log Out"
} else {
// if we are not logged in, the button should say "Log In"
"Log In"
}
}
})
// ANCHOR_END: if_else_improved
}
#[inline_props]
#[rustfmt::skip]
fn LogInWarning(cx: Scope, is_logged_in: bool) -> Element {
// ANCHOR: conditional_none
if *is_logged_in {
return None;
}
cx.render(rsx! {
a {
"You must be logged in to comment"
}
})
// ANCHOR_END: conditional_none
}

311
docs/guide/examples/custom_renderer.rs
View file

@ -1,311 +0,0 @@
use dioxus::html::input_data::keyboard_types::{Code, Key, Modifiers};
use dioxus::prelude::*;
use dioxus_native_core::exports::shipyard::Component;
use dioxus_native_core::node_ref::*;
use dioxus_native_core::prelude::*;
use dioxus_native_core::utils::cursor::{Cursor, Pos};
use dioxus_native_core_macro::partial_derive_state;
// ANCHOR: state_impl
struct FontSize(f64);
// All states need to derive Component
#[derive(Default, Debug, Copy, Clone, Component)]
struct Size(f64, f64);
/// Derive some of the boilerplate for the State implementation
#[partial_derive_state]
impl State for Size {
type ParentDependencies = ();
// The size of the current node depends on the size of its children
type ChildDependencies = (Self,);
type NodeDependencies = ();
// Size only cares about the width, height, and text parts of the current node
const NODE_MASK: NodeMaskBuilder<'static> = NodeMaskBuilder::new()
// Get access to the width and height attributes
.with_attrs(AttributeMaskBuilder::Some(&["width", "height"]))
// Get access to the text of the node
.with_text();
fn update<'a>(
&mut self,
node_view: NodeView<()>,
_node: <Self::NodeDependencies as Dependancy>::ElementBorrowed<'a>,
_parent: Option<<Self::ParentDependencies as Dependancy>::ElementBorrowed<'a>>,
children: Vec<<Self::ChildDependencies as Dependancy>::ElementBorrowed<'a>>,
context: &SendAnyMap,
) -> bool {
let font_size = context.get::<FontSize>().unwrap().0;
let mut width;
let mut height;
if let Some(text) = node_view.text() {
// if the node has text, use the text to size our object
width = text.len() as f64 * font_size;
height = font_size;
} else {
// otherwise, the size is the maximum size of the children
width = children
.iter()
.map(|(item,)| item.0)
.reduce(|accum, item| if accum >= item { accum } else { item })
.unwrap_or(0.0);
height = children
.iter()
.map(|(item,)| item.1)
.reduce(|accum, item| if accum >= item { accum } else { item })
.unwrap_or(0.0);
}
// if the node contains a width or height attribute it overrides the other size
for a in node_view.attributes().into_iter().flatten() {
match &*a.attribute.name {
"width" => width = a.value.as_float().unwrap(),
"height" => height = a.value.as_float().unwrap(),
// because Size only depends on the width and height, no other attributes will be passed to the member
_ => panic!(),
}
}
// to determine what other parts of the dom need to be updated we return a boolean that marks if this member changed
let changed = (width != self.0) || (height != self.1);
*self = Self(width, height);
changed
}
}
#[derive(Debug, Clone, Copy, PartialEq, Default, Component)]
struct TextColor {
r: u8,
g: u8,
b: u8,
}
#[partial_derive_state]
impl State for TextColor {
// TextColor depends on the TextColor part of the parent
type ParentDependencies = (Self,);
type ChildDependencies = ();
type NodeDependencies = ();
// TextColor only cares about the color attribute of the current node
const NODE_MASK: NodeMaskBuilder<'static> =
// Get access to the color attribute
NodeMaskBuilder::new().with_attrs(AttributeMaskBuilder::Some(&["color"]));
fn update<'a>(
&mut self,
node_view: NodeView<()>,
_node: <Self::NodeDependencies as Dependancy>::ElementBorrowed<'a>,
parent: Option<<Self::ParentDependencies as Dependancy>::ElementBorrowed<'a>>,
_children: Vec<<Self::ChildDependencies as Dependancy>::ElementBorrowed<'a>>,
_context: &SendAnyMap,
) -> bool {
// TextColor only depends on the color tag, so getting the first tag is equivilent to looking through all tags
let new = match node_view
.attributes()
.and_then(|mut attrs| attrs.next())
.and_then(|attr| attr.value.as_text())
{
// if there is a color tag, translate it
Some("red") => TextColor { r: 255, g: 0, b: 0 },
Some("green") => TextColor { r: 0, g: 255, b: 0 },
Some("blue") => TextColor { r: 0, g: 0, b: 255 },
Some(color) => panic!("unknown color {color}"),
// otherwise check if the node has a parent and inherit that color
None => match parent {
Some((parent,)) => *parent,
None => Self::default(),
},
};
// check if the member has changed
let changed = new != *self;
*self = new;
changed
}
}
#[derive(Debug, Clone, Copy, PartialEq, Default, Component)]
struct Border(bool);
#[partial_derive_state]
impl State for Border {
// TextColor depends on the TextColor part of the parent
type ParentDependencies = (Self,);
type ChildDependencies = ();
type NodeDependencies = ();
// Border does not depended on any other member in the current node
const NODE_MASK: NodeMaskBuilder<'static> =
// Get access to the border attribute
NodeMaskBuilder::new().with_attrs(AttributeMaskBuilder::Some(&["border"]));
fn update<'a>(
&mut self,
node_view: NodeView<()>,
_node: <Self::NodeDependencies as Dependancy>::ElementBorrowed<'a>,
_parent: Option<<Self::ParentDependencies as Dependancy>::ElementBorrowed<'a>>,
_children: Vec<<Self::ChildDependencies as Dependancy>::ElementBorrowed<'a>>,
_context: &SendAnyMap,
) -> bool {
// check if the node contians a border attribute
let new = Self(
node_view
.attributes()
.and_then(|mut attrs| attrs.next().map(|a| a.attribute.name == "border"))
.is_some(),
);
// check if the member has changed
let changed = new != *self;
*self = new;
changed
}
}
// ANCHOR_END: state_impl
// ANCHOR: rendering
fn main() -> Result<(), Box<dyn std::error::Error>> {
fn app(cx: Scope) -> Element {
let count = use_state(cx, || 0);
use_future(cx, (count,), |(count,)| async move {
loop {
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
count.set(*count + 1);
}
});
cx.render(rsx! {
div{
color: "red",
"{count}"
}
})
}
// create the vdom, the real_dom, and the binding layer between them
let mut vdom = VirtualDom::new(app);
let mut rdom: RealDom = RealDom::new([
Border::to_type_erased(),
TextColor::to_type_erased(),
Size::to_type_erased(),
]);
let mut dioxus_intigration_state = DioxusState::create(&mut rdom);
let mutations = vdom.rebuild();
// update the structure of the real_dom tree
dioxus_intigration_state.apply_mutations(&mut rdom, mutations);
let mut ctx = SendAnyMap::new();
// set the font size to 3.3
ctx.insert(FontSize(3.3));
// update the State for nodes in the real_dom tree
let _to_rerender = rdom.update_state(ctx);
// we need to run the vdom in a async runtime
tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()?
.block_on(async {
loop {
// wait for the vdom to update
vdom.wait_for_work().await;
// get the mutations from the vdom
let mutations = vdom.render_immediate();
// update the structure of the real_dom tree
dioxus_intigration_state.apply_mutations(&mut rdom, mutations);
// update the state of the real_dom tree
let mut ctx = SendAnyMap::new();
// set the font size to 3.3
ctx.insert(FontSize(3.3));
let _to_rerender = rdom.update_state(ctx);
// render...
rdom.traverse_depth_first(|node| {
let indent = " ".repeat(node.height() as usize);
let color = *node.get::<TextColor>().unwrap();
let size = *node.get::<Size>().unwrap();
let border = *node.get::<Border>().unwrap();
let id = node.id();
let node = node.node_type();
let node_type = &*node;
println!("{indent}{id:?} {color:?} {size:?} {border:?} {node_type:?}");
});
}
})
}
// ANCHOR_END: rendering
// ANCHOR: derive_state
// All states must derive Component (https://docs.rs/shipyard/latest/shipyard/derive.Component.html)
// They also must implement Default or provide a custom implementation of create in the State trait
#[derive(Default, Component)]
struct MyState;
/// Derive some of the boilerplate for the State implementation
#[partial_derive_state]
impl State for MyState {
// The states of the parent nodes this state depends on
type ParentDependencies = ();
// The states of the child nodes this state depends on
type ChildDependencies = (Self,);
// The states of the current node this state depends on
type NodeDependencies = ();
// The parts of the current text, element, or placeholder node in the tree that this state depends on
const NODE_MASK: NodeMaskBuilder<'static> = NodeMaskBuilder::new();
// How to update the state of the current node based on the state of the parent nodes, child nodes, and the current node
// Returns true if the node was updated and false if the node was not updated
fn update<'a>(
&mut self,
// The view of the current node limited to the parts this state depends on
_node_view: NodeView<()>,
// The state of the current node that this state depends on
_node: <Self::NodeDependencies as Dependancy>::ElementBorrowed<'a>,
// The state of the parent nodes that this state depends on
_parent: Option<<Self::ParentDependencies as Dependancy>::ElementBorrowed<'a>>,
// The state of the child nodes that this state depends on
_children: Vec<<Self::ChildDependencies as Dependancy>::ElementBorrowed<'a>>,
// The context of the current node used to pass global state into the tree
_context: &SendAnyMap,
) -> bool {
todo!()
}
// partial_derive_state will generate a default implementation of all the other methods
}
// ANCHOR_END: derive_state
#[allow(unused)]
// ANCHOR: cursor
fn text_editing() {
let mut cursor = Cursor::default();
let mut text = String::new();
// handle keyboard input with a max text length of 10
cursor.handle_input(
&Code::ArrowRight,
&Key::ArrowRight,
&Modifiers::empty(),
&mut text,
10,
);
// mannually select text between characters 0-5 on the first line (this could be from dragging with a mouse)
cursor.start = Pos::new(0, 0);
cursor.end = Some(Pos::new(5, 0));
// delete the selected text and move the cursor to the start of the selection
cursor.delete_selection(&mut text);
}
// ANCHOR_END: cursor

20
docs/guide/examples/dangerous_inner_html.rs
View file

@ -1,20 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
// ANCHOR: dangerous_inner_html
// this should come from a trusted source
let contents = "live <b>dangerously</b>";
cx.render(rsx! {
div {
dangerous_inner_html: "{contents}",
}
})
// ANCHOR_END: dangerous_inner_html
}

18
docs/guide/examples/event_click.rs
View file

@ -1,18 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
// ANCHOR: rsx
cx.render(rsx! {
button {
onclick: move |event| println!("Clicked! Event: {event:?}"),
"click me!"
}
})
// ANCHOR_END: rsx
}

32
docs/guide/examples/event_handler_prop.rs
View file

@ -1,32 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
fn App(cx: Scope) -> Element {
// ANCHOR: usage
cx.render(rsx! {
FancyButton {
on_click: move |event| println!("Clicked! {event:?}")
}
})
// ANCHOR_END: usage
}
// ANCHOR: component_with_handler
#[derive(Props)]
pub struct FancyButtonProps<'a> {
on_click: EventHandler<'a, MouseEvent>,
}
pub fn FancyButton<'a>(cx: Scope<'a, FancyButtonProps<'a>>) -> Element<'a> {
cx.render(rsx!(button {
class: "fancy-button",
onclick: move |evt| cx.props.on_click.call(evt),
"click me pls."
}))
}
// ANCHOR_END: component_with_handler

25
docs/guide/examples/event_nested.rs
View file

@ -1,25 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
// ANCHOR: rsx
cx.render(rsx! {
div {
onclick: move |_event| {},
"outer",
button {
onclick: move |event| {
// now, outer won't be triggered
event.stop_propagation();
},
"inner"
}
}
})
// ANCHOR_END: rsx
}

17
docs/guide/examples/event_prevent_default.rs
View file

@ -1,17 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
// ANCHOR: prevent_default
cx.render(rsx! {
input {
prevent_default: "oninput onclick",
}
})
// ANCHOR_END: prevent_default
}

21
docs/guide/examples/hello_world_desktop.rs
View file

@ -1,21 +0,0 @@
// ANCHOR: all
#![allow(non_snake_case)]
// import the prelude to get access to the `rsx!` macro and the `Scope` and `Element` types
use dioxus::prelude::*;
fn main() {
// launch the dioxus app in a webview
dioxus_desktop::launch(App);
}
// ANCHOR: component
// define a component that renders a div with the text "Hello, world!"
fn App(cx: Scope) -> Element {
cx.render(rsx! {
div {
"Hello, world!"
}
})
}
// ANCHOR_END: component
// ANCHOR_END: all

60
docs/guide/examples/hello_world_liveview.rs
View file

@ -1,60 +0,0 @@
// ANCHOR: all
use axum::{extract::ws::WebSocketUpgrade, response::Html, routing::get, Router};
use dioxus::prelude::*;
// ANCHOR: glue
#[tokio::main]
async fn main() {
let addr: std::net::SocketAddr = ([127, 0, 0, 1], 3030).into();
let view = dioxus_liveview::LiveViewPool::new();
let app = Router::new()
// The root route contains the glue code to connect to the WebSocket
.route(
"/",
get(move || async move {
Html(format!(
r#"
<!DOCTYPE html>
<html>
<head> <title>Dioxus LiveView with Axum</title> </head>
<body> <div id="main"></div> </body>
{glue}
</html>
"#,
// Create the glue code to connect to the WebSocket on the "/ws" route
glue = dioxus_liveview::interpreter_glue(&format!("ws://{addr}/ws"))
))
}),
)
// The WebSocket route is what Dioxus uses to communicate with the browser
.route(
"/ws",
get(move |ws: WebSocketUpgrade| async move {
ws.on_upgrade(move |socket| async move {
// When the WebSocket is upgraded, launch the LiveView with the app component
_ = view.launch(dioxus_liveview::axum_socket(socket), app).await;
})
}),
);
println!("Listening on http://{addr}");
axum::Server::bind(&addr.to_string().parse().unwrap())
.serve(app.into_make_service())
.await
.unwrap();
}
// ANCHOR_END: glue
// ANCHOR: app
fn app(cx: Scope) -> Element {
cx.render(rsx! {
div {
"Hello, world!"
}
})
}
// ANCHOR_END: app
// ANCHOR_END: all

63
docs/guide/examples/hello_world_ssr.rs
View file

@ -1,63 +0,0 @@
#![allow(unused)]
#![allow(non_snake_case)]
// ANCHOR: all
// ANCHOR: main
#![allow(non_snake_case)]
use axum::{response::Html, routing::get, Router};
// import the prelude to get access to the `rsx!` macro and the `Scope` and `Element` types
use dioxus::prelude::*;
#[tokio::main]
async fn main() {
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 3000));
println!("listening on http://{}", addr);
axum::Server::bind(&addr)
.serve(
Router::new()
.route("/", get(app_endpoint))
.into_make_service(),
)
.await
.unwrap();
}
// ANCHOR_END: main
// ANCHOR: endpoint
async fn app_endpoint() -> Html<String> {
// render the rsx! macro to HTML
Html(dioxus_ssr::render_lazy(rsx! {
div { "hello world!" }
}))
}
// ANCHOR_END: endpoint
// ANCHOR: second_endpoint
async fn second_app_endpoint() -> Html<String> {
// create a component that renders a div with the text "hello world"
fn app(cx: Scope) -> Element {
cx.render(rsx!(div { "hello world" }))
}
// create a VirtualDom with the app component
let mut app = VirtualDom::new(app);
// rebuild the VirtualDom before rendering
let _ = app.rebuild();
// render the VirtualDom to HTML
Html(dioxus_ssr::render(&app))
}
// ANCHOR_END: second_endpoint
// ANCHOR: component
// define a component that renders a div with the text "Hello, world!"
fn App(cx: Scope) -> Element {
cx.render(rsx! {
div {
"Hello, world!"
}
})
}
// ANCHOR_END: component
// ANCHOR_END: all

17
docs/guide/examples/hello_world_tui.rs
View file

@ -1,17 +0,0 @@
#![allow(non_snake_case)]
// import the prelude to get access to the `rsx!` macro and the `Scope` and `Element` types
use dioxus::prelude::*;
fn main() {
// launch the app in the terminal
dioxus_tui::launch(App);
}
// create a component that renders a div with the text "Hello, world!"
fn App(cx: Scope) -> Element {
cx.render(rsx! {
div {
"Hello, world!"
}
})
}

36
docs/guide/examples/hello_world_tui_no_ctrl_c.rs
View file

@ -1,36 +0,0 @@
// todo remove deprecated
#![allow(non_snake_case, deprecated)]
use dioxus::events::{KeyCode, KeyboardEvent};
use dioxus::prelude::*;
use dioxus_tui::TuiContext;
fn main() {
dioxus_tui::launch_cfg(
App,
dioxus_tui::Config::new()
.without_ctrl_c_quit()
// Some older terminals only support 16 colors or ANSI colors
// If your terminal is one of these, change this to BaseColors or ANSI
.with_rendering_mode(dioxus_tui::RenderingMode::Rgb),
);
}
fn App(cx: Scope) -> Element {
let tui_ctx: TuiContext = cx.consume_context().unwrap();
cx.render(rsx! {
div {
width: "100%",
height: "10px",
background_color: "red",
justify_content: "center",
align_items: "center",
onkeydown: move |k: KeyboardEvent| if let KeyCode::Q = k.key_code {
tui_ctx.quit();
},
"Hello world!"
}
})
}

17
docs/guide/examples/hello_world_web.rs
View file

@ -1,17 +0,0 @@
#![allow(non_snake_case)]
// import the prelude to get access to the `rsx!` macro and the `Scope` and `Element` types
use dioxus::prelude::*;
fn main() {
// launch the web app
dioxus_web::launch(App);
}
// create a component that renders a div with the text "Hello, world!"
fn App(cx: Scope) -> Element {
cx.render(rsx! {
div {
"Hello, world!"
}
})
}

38
docs/guide/examples/hooks_anti_patterns.rs
View file

@ -1,38 +0,0 @@
#![allow(unused)]
use dioxus::prelude::*;
fn main() {}
// ANCHOR: non_clone_state
use std::cell::RefCell;
use std::rc::Rc;
use std::sync::Arc;
struct UseState<'a, T> {
value: &'a RefCell<T>,
update: Arc<dyn Fn()>,
}
fn my_use_state<T: 'static>(cx: &ScopeState, init: impl FnOnce() -> T) -> UseState<T> {
// The update function will trigger a re-render in the component cx is attached to
let update = cx.schedule_update();
// Create the initial state
let value = cx.use_hook(|| RefCell::new(init()));
UseState { value, update }
}
impl<T: Clone> UseState<'_, T> {
fn get(&self) -> T {
self.value.borrow().clone()
}
fn set(&self, value: T) {
// Update the state
*self.value.borrow_mut() = value;
// Trigger a re-render on the component the state is from
(self.update)();
}
}
// ANCHOR_END: non_clone_state

68
docs/guide/examples/hooks_bad.rs
View file

@ -1,68 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
use std::collections::HashMap;
fn main() {
dioxus_desktop::launch(App);
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
let you_are_happy = true;
let you_know_it = false;
// ANCHOR: conditional
// ❌ don't call hooks in conditionals!
// We must ensure that the same hooks will be called every time
// But `if` statements only run if the conditional is true!
// So we might violate rule 2.
if you_are_happy && you_know_it {
let something = use_state(cx, || "hands");
println!("clap your {something}")
}
// ✅ instead, *always* call use_state
// You can put other stuff in the conditional though
let something = use_state(cx, || "hands");
if you_are_happy && you_know_it {
println!("clap your {something}")
}
// ANCHOR_END: conditional
// ANCHOR: closure
// ❌ don't call hooks inside closures!
// We can't guarantee that the closure, if used, will be called in the same order every time
let _a = || {
let b = use_state(cx, || 0);
b.get()
};
// ✅ instead, move hook `b` outside
let b = use_state(cx, || 0);
let _a = || b.get();
// ANCHOR_END: closure
let names: Vec<&str> = vec![];
// ANCHOR: loop
// `names` is a Vec<&str>
// ❌ Do not use hooks in loops!
// In this case, if the length of the Vec changes, we break rule 2
for _name in &names {
let is_selected = use_state(cx, || false);
println!("selected: {is_selected}");
}
// ✅ Instead, use a hashmap with use_ref
let selection_map = use_ref(cx, HashMap::<&str, bool>::new);
for name in &names {
let is_selected = selection_map.read()[name];
println!("selected: {is_selected}");
}
// ANCHOR_END: loop
cx.render(rsx!(()))
}

67
docs/guide/examples/hooks_composed.rs
View file

@ -1,67 +0,0 @@
#![allow(unused)]
use dioxus::prelude::*;
fn main() {}
struct AppSettings {}
// ANCHOR: wrap_context
fn use_settings(cx: &ScopeState) -> &UseSharedState<AppSettings> {
use_shared_state::<AppSettings>(cx).expect("App settings not provided")
}
// ANCHOR_END: wrap_context
// ANCHOR: use_storage
use gloo_storage::{LocalStorage, Storage};
use serde::{de::DeserializeOwned, Serialize};
/// A persistent storage hook that can be used to store data across application reloads.
#[allow(clippy::needless_return)]
pub fn use_persistent<T: Serialize + DeserializeOwned + Default + 'static>(
cx: &ScopeState,
// A unique key for the storage entry
key: impl ToString,
// A function that returns the initial value if the storage entry is empty
init: impl FnOnce() -> T,
) -> &UsePersistent<T> {
// Use the use_ref hook to create a mutable state for the storage entry
let state = use_ref(cx, move || {
// This closure will run when the hook is created
let key = key.to_string();
let value = LocalStorage::get(key.as_str()).ok().unwrap_or_else(init);
StorageEntry { key, value }
});
// Wrap the state in a new struct with a custom API
// Note: We use use_hook here so that this hook is easier to use in closures in the rsx. Any values with the same lifetime as the ScopeState can be used in the closure without cloning.
cx.use_hook(|| UsePersistent {
inner: state.clone(),
})
}
struct StorageEntry<T> {
key: String,
value: T,
}
/// Storage that persists across application reloads
pub struct UsePersistent<T: 'static> {
inner: UseRef<StorageEntry<T>>,
}
impl<T: Serialize + DeserializeOwned + Clone + 'static> UsePersistent<T> {
/// Returns a reference to the value
pub fn get(&self) -> T {
self.inner.read().value.clone()
}
/// Sets the value
pub fn set(&self, value: T) {
let mut inner = self.inner.write();
// Write the new value to local storage
LocalStorage::set(inner.key.as_str(), &value);
inner.value = value;
}
}
// ANCHOR_END: use_storage

31
docs/guide/examples/hooks_counter.rs
View file

@ -1,31 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: component
fn App(cx: Scope) -> Element {
// count will be initialized to 0 the first time the component is rendered
let mut count = use_state(cx, || 0);
cx.render(rsx!(
h1 { "High-Five counter: {count}" }
button {
onclick: move |_| {
// changing the count will cause the component to re-render
count += 1
},
"Up high!"
}
button {
onclick: move |_| {
// changing the count will cause the component to re-render
count -= 1
},
"Down low!"
}
))
}
// ANCHOR_END: component

24
docs/guide/examples/hooks_counter_two_state.rs
View file

@ -1,24 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: component
fn App(cx: Scope) -> Element {
// ANCHOR: use_state_calls
let mut count_a = use_state(cx, || 0);
let mut count_b = use_state(cx, || 0);
// ANCHOR_END: use_state_calls
cx.render(rsx!(
h1 { "Counter_a: {count_a}" }
button { onclick: move |_| count_a += 1, "a++" }
button { onclick: move |_| count_a -= 1, "a--" }
h1 { "Counter_b: {count_b}" }
button { onclick: move |_| count_b += 1, "b++" }
button { onclick: move |_| count_b -= 1, "b--" }
))
}
// ANCHOR_END: component

57
docs/guide/examples/hooks_custom_logic.rs
View file

@ -1,57 +0,0 @@
#![allow(unused)]
use dioxus::prelude::*;
fn main() {}
// ANCHOR: use_state
use std::cell::RefCell;
use std::rc::Rc;
use std::sync::Arc;
#[derive(Clone)]
struct UseState<T> {
value: Rc<RefCell<T>>,
update: Arc<dyn Fn()>,
}
fn my_use_state<T: 'static>(cx: &ScopeState, init: impl FnOnce() -> T) -> &UseState<T> {
cx.use_hook(|| {
// The update function will trigger a re-render in the component cx is attached to
let update = cx.schedule_update();
// Create the initial state
let value = Rc::new(RefCell::new(init()));
UseState { value, update }
})
}
impl<T: Clone> UseState<T> {
fn get(&self) -> T {
self.value.borrow().clone()
}
fn set(&self, value: T) {
// Update the state
*self.value.borrow_mut() = value;
// Trigger a re-render on the component the state is from
(self.update)();
}
}
// ANCHOR_END: use_state
// ANCHOR: use_context
pub fn use_context<T: 'static + Clone>(cx: &ScopeState) -> Option<&T> {
cx.use_hook(|| cx.consume_context::<T>()).as_ref()
}
pub fn use_context_provider<T: 'static + Clone>(cx: &ScopeState, f: impl FnOnce() -> T) -> &T {
cx.use_hook(|| {
let val = f();
// Provide the context state to the scope
cx.provide_context(val.clone());
val
})
}
// ANCHOR_END: use_context

22
docs/guide/examples/hooks_use_ref.rs
View file

@ -1,22 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: component
fn App(cx: Scope) -> Element {
let list = use_ref(cx, Vec::new);
cx.render(rsx!(
p { "Current list: {list.read():?}" }
button {
onclick: move |event| {
list.with_mut(|list| list.push(event));
},
"Click me!"
}
))
}
// ANCHOR_END: component

34
docs/guide/examples/hydration.rs
View file

@ -1,34 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
fn main() {
#[cfg(feature = "web")]
dioxus_web::launch_cfg(app, dioxus_web::Config::new().hydrate(true));
#[cfg(feature = "ssr")]
{
use dioxus_fullstack::prelude::*;
tokio::runtime::Runtime::new()
.unwrap()
.block_on(async move {
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 8080));
axum::Server::bind(&addr)
.serve(
axum::Router::new()
.serve_dioxus_application("", ServeConfigBuilder::new(app, ()))
.into_make_service(),
)
.await
.unwrap();
});
}
}
fn app(cx: Scope) -> Element {
let mut count = use_state(cx, || 0);
cx.render(rsx! {
h1 { "High-Five counter: {count}" }
button { onclick: move |_| count += 1, "Up high!" }
button { onclick: move |_| count -= 1, "Down low!" }
})
}

74
docs/guide/examples/hydration_props.rs
View file

@ -1,74 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
use dioxus_fullstack::prelude::*;
fn main() {
#[cfg(feature = "web")]
dioxus_web::launch_with_props(
app,
// Get the root props from the document
get_root_props_from_document().unwrap_or_default(),
dioxus_web::Config::new().hydrate(true),
);
#[cfg(feature = "ssr")]
{
use axum::extract::Path;
use axum::extract::State;
use axum::routing::get;
tokio::runtime::Runtime::new()
.unwrap()
.block_on(async move {
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 8080));
axum::Server::bind(&addr)
.serve(
axum::Router::new()
// Serve the dist folder with the static javascript and WASM files created by the dixous CLI
.serve_static_assets("./dist")
// Register server functions
.register_server_fns("")
// Connect to the hot reload server in debug mode
.connect_hot_reload()
// Render the application. This will serialize the root props (the intial count) into the HTML
.route(
"/",
get(move | State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
0,
)
.build(),
)
)}),
)
// Render the application with a different intial count
.route(
"/:initial_count",
get(move |Path(intial_count): Path<usize>, State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
intial_count,
)
.build(),
)
)}),
)
.with_state(SSRState::default())
.into_make_service(),
)
.await
.unwrap();
});
}
}
fn app(cx: Scope<usize>) -> Element {
let mut count = use_state(cx, || *cx.props);
cx.render(rsx! {
h1 { "High-Five counter: {count}" }
button { onclick: move |_| count += 1, "Up high!" }
button { onclick: move |_| count -= 1, "Down low!" }
})
}

21
docs/guide/examples/input_controlled.rs
View file

@ -1,21 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: component
fn App(cx: Scope) -> Element {
let name = use_state(cx, || "bob".to_string());
cx.render(rsx! {
input {
// we tell the component what to render
value: "{name}",
// and what to do when the value changes
oninput: move |evt| name.set(evt.value.clone()),
}
})
}
// ANCHOR_END: component

22
docs/guide/examples/input_uncontrolled.rs
View file

@ -1,22 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: component
fn App(cx: Scope) -> Element {
cx.render(rsx! {
form {
onsubmit: move |event| {
println!("Submitted! {event:?}")
},
input { name: "name", },
input { name: "age", },
input { name: "date", },
input { r#type: "submit", },
}
})
}
// ANCHOR_END: component

104
docs/guide/examples/meme_editor.rs
View file

@ -1,104 +0,0 @@
// ANCHOR: all
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(MemeEditor);
}
// ANCHOR: meme_editor
fn MemeEditor(cx: Scope) -> Element {
let container_style = r"
display: flex;
flex-direction: column;
gap: 16px;
margin: 0 auto;
width: fit-content;
";
let caption = use_state(cx, || "me waiting for my rust code to compile".to_string());
cx.render(rsx! {
div {
style: "{container_style}",
h1 { "Meme Editor" },
Meme {
caption: caption,
},
CaptionEditor {
caption: caption,
on_input: move |event: FormEvent| {caption.set(event.value.clone());},
},
}
})
}
// ANCHOR_END: meme_editor
// ANCHOR: meme_component
#[inline_props]
fn Meme<'a>(cx: Scope<'a>, caption: &'a str) -> Element<'a> {
let container_style = r#"
position: relative;
width: fit-content;
"#;
let caption_container_style = r#"
position: absolute;
bottom: 0;
left: 0;
right: 0;
padding: 16px 8px;
"#;
let caption_style = r"
font-size: 32px;
margin: 0;
color: white;
text-align: center;
";
cx.render(rsx!(
div {
style: "{container_style}",
img {
src: "https://i.imgflip.com/2zh47r.jpg",
height: "500px",
},
div {
style: "{caption_container_style}",
p {
style: "{caption_style}",
"{caption}"
}
}
}
))
}
// ANCHOR_END: meme_component
// ANCHOR: caption_editor
#[inline_props]
fn CaptionEditor<'a>(
cx: Scope<'a>,
caption: &'a str,
on_input: EventHandler<'a, FormEvent>,
) -> Element<'a> {
let input_style = r"
border: none;
background: cornflowerblue;
padding: 8px 16px;
margin: 0;
border-radius: 4px;
color: white;
";
cx.render(rsx!(input {
style: "{input_style}",
value: "{caption}",
oninput: move |event| on_input.call(event),
}))
}
// ANCHOR_END: caption_editor
// ANCHOR_END: all

185
docs/guide/examples/meme_editor_dark_mode.rs
View file

@ -1,185 +0,0 @@
// ANCHOR: all
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
// ANCHOR: DarkMode_struct
struct DarkMode(bool);
// ANCHOR_END: DarkMode_struct
#[rustfmt::skip]
pub fn App(cx: Scope) -> Element {
// ANCHOR: context_provider
use_shared_state_provider(cx, || DarkMode(false));
// ANCHOR_END: context_provider
let is_dark_mode = use_is_dark_mode(cx);
let wrapper_style = if is_dark_mode {
r"
background: #222;
min-height: 100vh;
"
} else {
r""
};
cx.render(rsx!(div {
style: "{wrapper_style}",
DarkModeToggle {},
MemeEditor {},
}))
}
#[rustfmt::skip]
pub fn use_is_dark_mode(cx: &ScopeState) -> bool {
// ANCHOR: use_context
let dark_mode_context = use_shared_state::<DarkMode>(cx);
// ANCHOR_END: use_context
dark_mode_context
.map(|context| context.read().0)
.unwrap_or(false)
}
// ANCHOR: toggle
pub fn DarkModeToggle(cx: Scope) -> Element {
let dark_mode = use_shared_state::<DarkMode>(cx).unwrap();
let style = if dark_mode.read().0 {
"color:white"
} else {
""
};
cx.render(rsx!(label {
style: "{style}",
"Dark Mode",
input {
r#type: "checkbox",
oninput: move |event| {
let is_enabled = event.value == "true";
dark_mode.write().0 = is_enabled;
},
},
}))
}
// ANCHOR_END: toggle
// ANCHOR: meme_editor
fn MemeEditor(cx: Scope) -> Element {
let is_dark_mode = use_is_dark_mode(cx);
let heading_style = if is_dark_mode { "color: white" } else { "" };
let container_style = r"
display: flex;
flex-direction: column;
gap: 16px;
margin: 0 auto;
width: fit-content;
";
let caption = use_state(cx, || "me waiting for my rust code to compile".to_string());
cx.render(rsx! {
div {
style: "{container_style}",
h1 {
style: "{heading_style}",
"Meme Editor"
},
Meme {
caption: caption,
},
CaptionEditor {
caption: caption,
on_input: move |event: FormEvent| {caption.set(event.value.clone());},
},
}
})
}
// ANCHOR_END: meme_editor
// ANCHOR: meme_component
#[inline_props]
fn Meme<'a>(cx: Scope<'a>, caption: &'a str) -> Element<'a> {
let container_style = r"
position: relative;
width: fit-content;
";
let caption_container_style = r"
position: absolute;
bottom: 0;
left: 0;
right: 0;
padding: 16px 8px;
";
let caption_style = r"
font-size: 32px;
margin: 0;
color: white;
text-align: center;
";
cx.render(rsx!(
div {
style: "{container_style}",
img {
src: "https://i.imgflip.com/2zh47r.jpg",
height: "500px",
},
div {
style: "{caption_container_style}",
p {
style: "{caption_style}",
"{caption}"
}
}
}
))
}
// ANCHOR_END: meme_component
// ANCHOR: caption_editor
#[inline_props]
fn CaptionEditor<'a>(
cx: Scope<'a>,
caption: &'a str,
on_input: EventHandler<'a, FormEvent>,
) -> Element<'a> {
let is_dark_mode = use_is_dark_mode(cx);
let colors = if is_dark_mode {
r"
background: cornflowerblue;
color: white;
"
} else {
r"
background: #def;
color: black;
"
};
let input_style = r"
border: none;
padding: 8px 16px;
margin: 0;
border-radius: 4px;
";
cx.render(rsx!(input {
style: "{input_style}{colors}",
value: "{caption}",
oninput: move |event| on_input.call(event),
}))
}
// ANCHOR_END: caption_editor
// ANCHOR_END: all

108
docs/guide/examples/readme_expanded.rs
View file

@ -1,108 +0,0 @@
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(app);
}
fn app(cx: Scope) -> Element {
let mut count = use_state(cx, || 0);
cx.render(
// rsx expands to LazyNodes::new
::dioxus::core::LazyNodes::new(
move |__cx: &::dioxus::core::ScopeState| -> ::dioxus::core::VNode {
// The template is every static part of the rsx
static TEMPLATE: ::dioxus::core::Template = ::dioxus::core::Template {
// This is the source location of the rsx that generated this template. This is used to make hot rsx reloading work. Hot rsx reloading just replaces the template with a new one generated from the rsx by the CLI.
name: "examples\\readme.rs:14:15:250",
// The root nodes are the top level nodes of the rsx
roots: &[
// The h1 node
::dioxus::core::TemplateNode::Element {
// Find the built in h1 tag in the dioxus_elements crate exported by the dioxus html crate
tag: dioxus_elements::h1::TAG_NAME,
namespace: dioxus_elements::h1::NAME_SPACE,
attrs: &[],
// The children of the h1 node
children: &[
// The dynamic count text node
// Any nodes that are dynamic have a dynamic placeholder with a unique index
::dioxus::core::TemplateNode::DynamicText {
// This index is used to find what element in `dynamic_nodes` to use instead of the placeholder
id: 0usize,
},
],
},
// The up high button node
::dioxus::core::TemplateNode::Element {
tag: dioxus_elements::button::TAG_NAME,
namespace: dioxus_elements::button::NAME_SPACE,
attrs: &[
// The dynamic onclick listener attribute
// Any attributes that are dynamic have a dynamic placeholder with a unique index.
::dioxus::core::TemplateAttribute::Dynamic {
// Similar to dynamic nodes, dynamic attributes have a unique index used to find the attribute in `dynamic_attrs` to use instead of the placeholder
id: 0usize,
},
],
children: &[::dioxus::core::TemplateNode::Text { text: "Up high!" }],
},
// The down low button node
::dioxus::core::TemplateNode::Element {
tag: dioxus_elements::button::TAG_NAME,
namespace: dioxus_elements::button::NAME_SPACE,
attrs: &[
// The dynamic onclick listener attribute
::dioxus::core::TemplateAttribute::Dynamic { id: 1usize },
],
children: &[::dioxus::core::TemplateNode::Text { text: "Down low!" }],
},
],
// Node paths is a list of paths to every dynamic node in the rsx
node_paths: &[
// The first node path is the path to the dynamic node with an id of 0 (the count text node)
&[
// Go to the index 0 root node
0u8,
//
// Go to the first child of the root node
0u8,
],
],
// Attr paths is a list of paths to every dynamic attribute in the rsx
attr_paths: &[
// The first attr path is the path to the dynamic attribute with an id of 0 (the up high button onclick listener)
&[
// Go to the index 1 root node
1u8,
],
// The second attr path is the path to the dynamic attribute with an id of 1 (the down low button onclick listener)
&[
// Go to the index 2 root node
2u8,
],
],
};
// The VNode is a reference to the template with the dynamic parts of the rsx
::dioxus::core::VNode {
parent: None,
key: None,
// The static template this node will use. The template is stored in a Cell so it can be replaced with a new template when hot rsx reloading is enabled
template: std::cell::Cell::new(TEMPLATE),
root_ids: dioxus::core::exports::bumpalo::collections::Vec::new_in(__cx.bump())
.into(),
dynamic_nodes: __cx.bump().alloc([
// The dynamic count text node (dynamic node id 0)
__cx.text_node(format_args!("High-Five counter: {0}", count)),
]),
dynamic_attrs: __cx.bump().alloc([
// The dynamic up high button onclick listener (dynamic attribute id 0)
dioxus_elements::events::onclick(__cx, move |_| count += 1),
// The dynamic down low button onclick listener (dynamic attribute id 1)
dioxus_elements::events::onclick(__cx, move |_| count -= 1),
]),
}
},
),
)
}

98
docs/guide/examples/rendering_lists.rs
View file

@ -1,98 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[derive(PartialEq, Clone)]
struct Comment {
content: String,
id: usize,
}
#[rustfmt::skip]
pub fn App(cx: Scope) -> Element {
// ANCHOR: render_list
let comment_field = use_state(cx, String::new);
let mut next_id = use_state(cx, || 0);
let comments = use_ref(cx, Vec::<Comment>::new);
let comments_lock = comments.read();
let comments_rendered = comments_lock.iter().map(|comment| {
rsx!(CommentComponent {
key: "{comment.id}",
comment: comment.clone(),
})
});
cx.render(rsx!(
form {
onsubmit: move |_| {
comments.write().push(Comment {
content: comment_field.get().clone(),
id: *next_id.get(),
});
next_id += 1;
comment_field.set(String::new());
},
input {
value: "{comment_field}",
oninput: |event| comment_field.set(event.value.clone()),
}
input {
r#type: "submit",
}
},
comments_rendered,
))
// ANCHOR_END: render_list
}
#[rustfmt::skip]
pub fn AppForLoop(cx: Scope) -> Element {
// ANCHOR: render_list_for_loop
let comment_field = use_state(cx, String::new);
let mut next_id = use_state(cx, || 0);
let comments = use_ref(cx, Vec::<Comment>::new);
cx.render(rsx!(
form {
onsubmit: move |_| {
comments.write().push(Comment {
content: comment_field.get().clone(),
id: *next_id.get(),
});
next_id += 1;
comment_field.set(String::new());
},
input {
value: "{comment_field}",
oninput: |event| comment_field.set(event.value.clone()),
}
input {
r#type: "submit",
}
},
for comment in &*comments.read() {
// Notice the body of this for loop is rsx code, not an expression
CommentComponent {
key: "{comment.id}",
comment: comment.clone(),
}
}
))
// ANCHOR_END: render_list_for_loop
}
#[inline_props]
fn CommentComponent(cx: Scope, comment: Comment) -> Element {
cx.render(rsx!(div {
"Comment by anon:",
p { "{comment.content}" }
button { "Reply" },
}))
}

169
docs/guide/examples/rsx_overview.rs
View file

@ -1,169 +0,0 @@
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
pub fn App(cx: Scope) -> Element {
cx.render(rsx!(
Empty {},
Children {},
Fragments {},
Attributes {},
VariableAttributes {},
CustomAttributes {},
Formatting {},
Expression {},
))
}
#[rustfmt::skip]
pub fn Empty(cx: Scope) -> Element {
// ANCHOR: empty
cx.render(rsx!(div {
// attributes / listeners
// children
}))
// ANCHOR_END: empty
}
#[rustfmt::skip]
pub fn Children(cx: Scope) -> Element {
// ANCHOR: children
cx.render(rsx!(ol {
li {"First Item"}
li {"Second Item"}
li {"Third Item"}
}))
// ANCHOR_END: children
}
#[rustfmt::skip]
pub fn Fragments(cx: Scope) -> Element {
// ANCHOR: fragments
cx.render(rsx!(
p {"First Item"},
p {"Second Item"},
Fragment {
span { "a group" },
span { "of three" },
span { "items" },
}
))
// ANCHOR_END: fragments
}
#[rustfmt::skip]
pub fn ManyRoots(cx: Scope) -> Element {
// ANCHOR: manyroots
cx.render(rsx!(
p {"First Item"},
p {"Second Item"},
))
// ANCHOR_END: manyroots
}
#[rustfmt::skip]
pub fn Attributes(cx: Scope) -> Element {
// ANCHOR: attributes
cx.render(rsx!(a {
href: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
class: "primary_button",
color: "red",
}))
// ANCHOR_END: attributes
}
#[rustfmt::skip]
pub fn VariableAttributes(cx: Scope) -> Element {
// ANCHOR: variable_attributes
let written_in_rust = true;
let button_type = "button";
cx.render(rsx!(button {
disabled: "{written_in_rust}",
class: "{button_type}",
"Rewrite it in rust"
}))
// ANCHOR_END: variable_attributes
}
#[rustfmt::skip]
pub fn CustomAttributes(cx: Scope) -> Element {
// ANCHOR: custom_attributes
cx.render(rsx!(b {
"customAttribute": "value",
}))
// ANCHOR_END: custom_attributes
}
#[rustfmt::skip]
pub fn Formatting(cx: Scope) -> Element {
// ANCHOR: formatting
let coordinates = (42, 0);
let country = "es";
cx.render(rsx!(div {
class: "country-{country}",
"position": "{coordinates:?}",
// arbitrary expressions are allowed,
// as long as they don't contain `{}`
div {
"{country.to_uppercase()}"
},
div {
"{7*6}"
},
// {} can be escaped with {{}}
div {
"{{}}"
},
}))
// ANCHOR_END: formatting
}
#[rustfmt::skip]
pub fn Expression(cx: Scope) -> Element {
// ANCHOR: expression
let text = "Dioxus";
cx.render(rsx!(span {
text.to_uppercase(),
// create a list of text from 0 to 9
(0..10).map(|i| rsx!{ i.to_string() })
}))
// ANCHOR_END: expression
}
#[rustfmt::skip]
pub fn Loops(cx: Scope) -> Element {
// ANCHOR: loops
cx.render(rsx!{
// use a for loop where the body itself is RSX
div {
// create a list of text from 0 to 9
for i in 0..3 {
// NOTE: the body of the loop is RSX not a rust statement
div {
"{i}"
}
}
}
// iterator equivalent
div {
(0..3).map(|i| rsx!{ div { "{i}" } })
}
})
// ANCHOR_END: loops
}
#[rustfmt::skip]
pub fn IfStatements(cx: Scope) -> Element {
// ANCHOR: ifstatements
cx.render(rsx!{
// use if statements without an else
if true {
rsx!(div { "true" })
}
})
// ANCHOR_END: ifstatements
}

30
docs/guide/examples/server_basic.rs
View file

@ -1,30 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
#[tokio::main]
async fn main() {
#[cfg(feature = "ssr")]
{
use dioxus_fullstack::prelude::*;
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 8080));
axum::Server::bind(&addr)
.serve(
axum::Router::new()
.serve_dioxus_application("", ServeConfigBuilder::new(app, ()))
.into_make_service(),
)
.await
.unwrap();
}
}
fn app(cx: Scope) -> Element {
let mut count = use_state(cx, || 0);
cx.render(rsx! {
h1 { "High-Five counter: {count}" }
button { onclick: move |_| count += 1, "Up high!" }
button { onclick: move |_| count -= 1, "Down low!" }
})
}

109
docs/guide/examples/server_context.rs
View file

@ -1,109 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
use dioxus_fullstack::prelude::*;
fn main() {
#[cfg(feature = "web")]
dioxus_web::launch_with_props(
app,
// Get the root props from the document
get_root_props_from_document().unwrap_or_default(),
dioxus_web::Config::new().hydrate(true),
);
#[cfg(feature = "ssr")]
{
use axum::extract::Path;
use axum::extract::State;
use axum::routing::get;
tokio::runtime::Runtime::new()
.unwrap()
.block_on(async move {
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 8080));
axum::Server::bind(&addr)
.serve(
axum::Router::new()
// Serve the dist folder with the static javascript and WASM files created by the dixous CLI
.serve_static_assets("./dist")
// Register server functions
.register_server_fns("")
// Connect to the hot reload server in debug mode
.connect_hot_reload()
// Render the application. This will serialize the root props (the intial count) into the HTML
.route(
"/",
get(move |State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
0,
)
.build(),
)
)}),
)
// Render the application with a different intial count
.route(
"/:initial_count",
get(move |Path(intial_count): Path<usize>, State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
intial_count,
)
.build(),
)
)}),
)
.with_state(SSRState::default())
.into_make_service(),
)
.await
.unwrap();
});
}
}
fn app(cx: Scope<usize>) -> Element {
let mut count = use_state(cx, || *cx.props);
cx.render(rsx! {
h1 { "High-Five counter: {count}" }
button { onclick: move |_| count += 1, "Up high!" }
button { onclick: move |_| count -= 1, "Down low!" }
button {
onclick: move |_| {
to_owned![count];
async move {
// Call the server function just like a local async function
if let Ok(new_count) = double_server(*count.current()).await {
count.set(new_count);
}
}
},
"Double"
}
})
}
// We use the "getcbor" encoding to make caching easier
#[server(DoubleServer, "", "getcbor")]
async fn double_server(number: usize) -> Result<usize, ServerFnError> {
let cx = server_context();
// Perform some expensive computation or access a database on the server
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
let result = number * 2;
println!(
"User Agent {:?}",
cx.request_parts().headers.get("User-Agent")
);
// Set the cache control header to 1 hour on the post request
cx.response_headers_mut()
.insert("Cache-Control", "max-age=3600".parse().unwrap());
println!("server calculated {result}");
Ok(result)
}

134
docs/guide/examples/server_context_state.rs
View file

@ -1,134 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
use dioxus_fullstack::prelude::*;
#[cfg(feature = "ssr")]
#[derive(Default, Clone)]
struct ServerFunctionState {
call_count: std::sync::Arc<std::sync::atomic::AtomicUsize>,
}
fn main() {
#[cfg(feature = "web")]
dioxus_web::launch_with_props(
app,
// Get the root props from the document
get_root_props_from_document().unwrap_or_default(),
dioxus_web::Config::new().hydrate(true),
);
#[cfg(feature = "ssr")]
{
use axum::body::Body;
use axum::extract::Path;
use axum::extract::State;
use axum::http::Request;
use axum::routing::get;
use std::sync::Arc;
tokio::runtime::Runtime::new()
.unwrap()
.block_on(async move {
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 8080));
axum::Server::bind(&addr)
.serve(
axum::Router::new()
// Serve the dist folder with the static javascript and WASM files created by the dixous CLI
.serve_static_assets("./dist")
// Register server functions
.register_server_fns_with_handler("", |func| {
move |State(server_fn_state): State<ServerFunctionState>, req: Request<Body>| async move {
let (parts, body) = req.into_parts();
let parts: Arc<RequestParts> = Arc::new(parts.into());
let mut server_context = DioxusServerContext::new(parts.clone());
server_context.insert(server_fn_state);
server_fn_handler(server_context, func.clone(), parts, body).await
}
})
.with_state(ServerFunctionState::default())
// Connect to the hot reload server in debug mode
.connect_hot_reload()
// Render the application. This will serialize the root props (the intial count) into the HTML
.route(
"/",
get(move |State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
0,
)
.build(),
)
)}),
)
// Render the application with a different intial count
.route(
"/:initial_count",
get(move |Path(intial_count): Path<usize>, State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
intial_count,
)
.build(),
)
)}),
)
.with_state(SSRState::default())
.into_make_service(),
)
.await
.unwrap();
});
}
}
fn app(cx: Scope<usize>) -> Element {
let mut count = use_state(cx, || *cx.props);
cx.render(rsx! {
h1 { "High-Five counter: {count}" }
button { onclick: move |_| count += 1, "Up high!" }
button { onclick: move |_| count -= 1, "Down low!" }
button {
onclick: move |_| {
to_owned![count];
async move {
// Call the server function just like a local async function
if let Ok(new_count) = double_server(*count.current()).await {
count.set(new_count);
}
}
},
"Double"
}
})
}
// We use the "getcbor" encoding to make caching easier
#[server(DoubleServer, "", "getcbor")]
async fn double_server(number: usize) -> Result<usize, ServerFnError> {
// Perform some expensive computation or access a database on the server
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
let result = number * 2;
let cx = server_context();
println!(
"User Agent {:?}",
cx.request_parts().headers.get("User-Agent")
);
// Set the cache control header to 1 hour on the post request
cx.response_headers_mut()
.insert("Cache-Control", "max-age=3600".parse().unwrap());
// Get the server function state
let server_fn_state = cx.get::<ServerFunctionState>().unwrap();
let call_count = server_fn_state
.call_count
.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
println!("server functions have been called {call_count} times");
println!("server calculated {result}");
Ok(result)
}

96
docs/guide/examples/server_function.rs
View file

@ -1,96 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
use dioxus_fullstack::prelude::*;
fn main() {
#[cfg(feature = "web")]
dioxus_web::launch_with_props(
app,
// Get the root props from the document
get_root_props_from_document().unwrap_or_default(),
dioxus_web::Config::new().hydrate(true),
);
#[cfg(feature = "ssr")]
{
use axum::extract::Path;
use axum::extract::State;
use axum::routing::get;
tokio::runtime::Runtime::new()
.unwrap()
.block_on(async move {
let addr = std::net::SocketAddr::from(([127, 0, 0, 1], 8080));
axum::Server::bind(&addr)
.serve(
axum::Router::new()
// Serve the dist folder with the static javascript and WASM files created by the dixous CLI
.serve_static_assets("./dist")
// Register server functions
.register_server_fns("")
// Connect to the hot reload server in debug mode
.connect_hot_reload()
// Render the application. This will serialize the root props (the intial count) into the HTML
.route(
"/",
get(move |Path(intial_count): Path<usize>, State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
intial_count,
)
.build(),
)
)}),
)
// Render the application with a different intial count
.route(
"/:initial_count",
get(move |Path(intial_count): Path<usize>, State(ssr_state): State<SSRState>| async move { axum::body::Full::from(
ssr_state.render(
&ServeConfigBuilder::new(
app,
intial_count,
)
.build(),
)
)}),
)
.with_state(SSRState::default())
.into_make_service(),
)
.await
.unwrap();
});
}
}
fn app(cx: Scope<usize>) -> Element {
let mut count = use_state(cx, || *cx.props);
cx.render(rsx! {
h1 { "High-Five counter: {count}" }
button { onclick: move |_| count += 1, "Up high!" }
button { onclick: move |_| count -= 1, "Down low!" }
button {
onclick: move |_| {
to_owned![count];
async move {
// Call the server function just like a local async function
if let Ok(new_count) = double_server(*count.current()).await {
count.set(new_count);
}
}
},
"Double"
}
})
}
#[server(DoubleServer)]
async fn double_server(number: usize) -> Result<usize, ServerFnError> {
// Perform some expensive computation or access a database on the server
tokio::time::sleep(std::time::Duration::from_secs(1)).await;
let result = number * 2;
println!("server calculated {result}");
Ok(result)
}

84
docs/guide/examples/spawn.rs
View file

@ -1,84 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
fn App(cx: Scope) -> Element {
// ANCHOR: spawn
let logged_in = use_state(cx, || false);
let log_in = move |_| {
cx.spawn({
let logged_in = logged_in.to_owned();
async move {
let resp = reqwest::Client::new()
.post("http://example.com/login")
.send()
.await;
match resp {
Ok(_data) => {
println!("Login successful!");
logged_in.set(true);
}
Err(_err) => {
println!(
"Login failed - you need a login server running on localhost:8080."
)
}
}
}
});
};
cx.render(rsx! {
button {
onclick: log_in,
"Login",
}
})
// ANCHOR_END: spawn
}
pub fn Tokio(cx: Scope) -> Element {
let _ = || {
// ANCHOR: tokio
cx.spawn(async {
let _ = tokio::spawn(async {}).await;
let _ = tokio::task::spawn_local(async {
// some !Send work
})
.await;
});
// ANCHOR_END: tokio
};
cx.render(rsx!(()))
}
pub fn ToOwnedMacro(cx: Scope) -> Element {
let count = use_state(cx, || 0);
let age = use_state(cx, || 0);
let name = use_state(cx, || 0);
let description = use_state(cx, || 0);
let _ = || {
// ANCHOR: to_owned_macro
use dioxus::hooks::to_owned;
cx.spawn({
to_owned![count, age, name, description];
async move {
// ...
}
});
// ANCHOR_END: to_owned_macro
};
cx.render(rsx!(()))
}

62
docs/guide/examples/use_future.rs
View file

@ -1,62 +0,0 @@
#![allow(non_snake_case, unused)]
use dioxus::prelude::*;
fn main() {
dioxus_desktop::launch(App);
}
#[derive(serde::Deserialize, Debug)]
struct ApiResponse {
#[serde(rename = "message")]
image_url: String,
}
#[rustfmt::skip]
fn App(cx: Scope) -> Element {
// ANCHOR: use_future
let future = use_future(cx, (), |_| async move {
reqwest::get("https://dog.ceo/api/breeds/image/random")
.await
.unwrap()
.json::<ApiResponse>()
.await
});
// ANCHOR_END: use_future
// ANCHOR: render
cx.render(match future.value() {
Some(Ok(response)) => rsx! {
button {
onclick: move |_| future.restart(),
"Click to fetch another doggo"
}
div {
img {
max_width: "500px",
max_height: "500px",
src: "{response.image_url}",
}
}
},
Some(Err(_)) => rsx! { div { "Loading dogs failed" } },
None => rsx! { div { "Loading dogs..." } },
})
// ANCHOR_END: render
}
#[rustfmt::skip]
#[inline_props]
fn RandomDog(cx: Scope, breed: String) -> Element {
// ANCHOR: dependency
let future = use_future(cx, (breed,), |(breed,)| async move {
reqwest::get(format!("https://dog.ceo/api/breed/{breed}/images/random"))
.await
.unwrap()
.json::<ApiResponse>()
.await
});
// ANCHOR_END: dependency
cx.render(rsx!(()))
}

57
docs/guide/src/en/SUMMARY.md
View file

@ -1,57 +0,0 @@
# Summary
[Introduction](index.md)
- [Getting Started](getting_started/index.md)
- [Desktop](getting_started/desktop.md)
- [Web](getting_started/web.md)
- [Server-Side Rendering](getting_started/ssr.md)
- [Fullstack](getting_started/fullstack.md)
- [Liveview](getting_started/liveview.md)
- [Terminal UI](getting_started/tui.md)
- [Mobile](getting_started/mobile.md)
- [Hot Reloading](getting_started/hot_reload.md)
- [Describing the UI](describing_ui/index.md)
- [Special Attributes](describing_ui/special_attributes.md)
- [Components](describing_ui/components.md)
- [Props](describing_ui/component_props.md)
- [Component Children](describing_ui/component_children.md)
- [Interactivity](interactivity/index.md)
- [Event Listeners](interactivity/event_handlers.md)
- [Hooks & Component State](interactivity/hooks.md)
- [User Input](interactivity/user_input.md)
- [Sharing State](interactivity/sharing_state.md)
- [Memoization](interactivity/memoization.md)
- [Custom Hooks](interactivity/custom_hooks.md)
- [Dynamic Rendering](interactivity/dynamic_rendering.md)
- [Routing](interactivity/router.md)
- [Async](async/index.md)
- [UseEffect](async/use_effect.md)
- [UseFuture](async/use_future.md)
- [UseCoroutine](async/use_coroutine.md)
- [Spawning Futures](async/spawn.md)
- [Best Practices](best_practices/index.md)
- [Error Handling](best_practices/error_handling.md)
- [Antipatterns](best_practices/antipatterns.md)
- [Publishing](publishing/index.md)
- [Desktop](publishing/desktop.md)
- [Web](publishing/web.md)
---
- [Fullstack](fullstack/index.md)
- [Getting Started](fullstack/getting_started.md)
- [Communicating with the Server](fullstack/server_functions.md)
---
- [Custom Renderer](custom_renderer/index.md)
---
- [Contributing](contributing/index.md)
- [Project Structure](contributing/project_structure.md)
- [Walkthrough of Internals](contributing/walkthrough_readme.md)
- [Guiding Principles](contributing/guiding_principles.md)
- [Roadmap](contributing/roadmap.md)

6
docs/guide/src/en/__unused/README.md
View file

@ -1,6 +0,0 @@
This directory includes:
- Very outdated docs
- Docs for features which haven't been implemented (yet?)
- Information which has already been covered in the guide in a more organized fashion
- A few things yet to be integrated into the guide nicely

33
docs/guide/src/en/__unused/advanced-guides/06-subscription-api.md
View file

@ -1,33 +0,0 @@
# Subscriptions
Yew subscriptions are used to schedule update for components into the future. The `Context` object can create subscriptions:
```rust, no_run
fn Component(cx: Component) -> DomTree {
let update = cx.schedule();
// Now, when the subscription is called, the component will be re-evaluated
update.consume();
}
```
Whenever a component's subscription is called, the component will then re-evaluated. You can consider the input properties of
a component to be just another form of subscription. By default, the Dioxus component system automatically diffs a component's props
when the parent function is called, and if the props are different, the child component's subscription is called.
The subscription API exposes this functionality allowing hooks and state management solutions the ability to update components whenever
some state or event occurs outside of the component. For instance, the `use_context` hook uses this to subscribe components that use a
particular context.
```rust, no_run
fn use_context<I>(cx: Scope<T>) -> I {
}
```

82
docs/guide/src/en/__unused/advanced-guides/10-concurrent-mode.md
View file

@ -1,82 +0,0 @@
# Concurrent mode
Concurrent mode provides a mechanism for building efficient asynchronous components. With this feature, components don't need to render immediately, and instead can schedule a future render by returning a future.
To make a component asynchronous, simply change its function signature to async.
```rust, no_run
fn Example(cx: Scope) -> Vnode {
rsx!{ <div> "Hello world!" </div> }
}
```
becomes
```rust, no_run
async fn Example(cx: Scope) -> Vnode {
rsx!{ <div> "Hello world!" </div> }
}
```
Now, logic in components can be awaited to delay updates of the component and its children. Like so:
```rust, no_run
async fn Example(cx: Scope) -> Vnode {
let name = fetch_name().await;
rsx!{ <div> "Hello {name}" </div> }
}
async fetch_name() -> String {
// ...
}
```
This component will only schedule its render once the fetch is complete. However, we _don't_ recommend using async/await directly in your components.
Async is a notoriously challenging yet rewarding tool for efficient tools. If not careful, locking and unlocking shared aspects of the component's context can lead to data races and panics. If a shared resource is locked while the component is awaiting, then other components can be locked or panic when trying to access the same resource. These rules are especially important when references to shared global state are accessed using the context object's lifetime. If mutable references to data captured immutably by the context are taken, then the component will panic, causing confusion.
Instead, we suggest using hooks and future combinators that can safely utilize the safeguards of the component's Context when interacting with async tasks.
As part of our Dioxus hooks crate, we provide a data loader hook which pauses a component until its async dependencies are ready. This caches requests, reruns the fetch if dependencies have changed, and provides the option to render something else while the component is loading.
```rust, no_run
async fn ExampleLoader(cx: Scope) -> Vnode {
/*
Fetch, pause the component from rendering at all.
The component is locked while waiting for the request to complete
While waiting, an alternate component is scheduled in its place.
This API stores the result on the Context object, so the loaded data is taken as reference.
*/
let name: &Result<SomeStructure> = use_fetch_data("http://example.com/json", ())
.place_holder(|cx| rsx!{<div> "loading..." </div>})
.delayed_place_holder(1000, |cx| rsx!{ <div> "still loading..." </div>})
.await;
match name {
Ok(name) => rsx! { <div> "Hello {something}" </div> },
Err(e) => rsx! { <div> "An error occurred :(" </div>}
}
}
```
```rust, no_run
async fn Example(cx: Scope) -> DomTree {
// Diff this set between the last set
// Check if we have any outstanding tasks?
//
// Eventually, render the component into the VDOM when the future completes
<div>
<Example />
</div>
// Render a div, queue a component
// Render the placeholder first, then when the component is ready, then render the component
<div>
<Suspense placeholder={html!{<div>"Loading"</div>}}>
<Example />
</Suspense>
</div>
}
```

58
docs/guide/src/en/__unused/advanced-guides/11-arena-memo.md
View file

@ -1,58 +0,0 @@
# Memoization and the arena allocator
Dioxus differs slightly from other UI virtual doms in some subtle ways due to its memory allocator.
One important aspect to understand is how props are passed down from parent components to children. All "components" (custom user-made UI elements) are tightly allocated together in an arena. However, because props and hooks are generically typed, they are casted to `Any` and allocated on the heap – not in the arena with the components.
With this system, we try to be more efficient when leaving the component arena and entering the heap. By default, props are memoized between renders using COW and context. This makes props comparisons fast – done via ptr comparisons on the cow pointer. Because memoization is done by default, parent re-renders will _not_ cascade to children if the child's props did not change.
https://dmitripavlutin.com/use-react-memo-wisely/
This behavior is defined as an attribute implicit to user components. When in React land you might wrap a component with `react.memo`, Dioxus components are automatically memoized via an implicit attribute. You can manually configure this behavior on any component with "nomemo" to disable memoization.
```rust, no_run
fn test() -> DomTree {
html! {
<>
<SomeComponent nomemo />
// same as
<SomeComponent nomemo=true />
</>
}
}
static TestComponent: Component = |cx| html!{<div>"Hello world"</div>};
static TestComponent: Component = |cx|{
let g = "BLAH";
html! {
<div> "Hello world" </div>
}
};
#[inline_props]
fn test_component(cx: Scope, name: String) -> Element {
render!("Hello, {name}")
}
```
## Why this behavior?
"This is different than React, why differ?".
Take a component like this:
```rust, no_run
fn test(cx: Scope) -> DomTree {
let Bundle { alpha, beta, gamma } = use_context::<SomeContext>(cx);
html! {
<div>
<Component name=alpha />
<Component name=beta />
<Component name=gamma />
</div>
}
}
```
While the contents of the destructured bundle might change, not every child component will need to be re-rendered every time the context changes.

150
docs/guide/src/en/__unused/advanced-guides/12-signals.md
View file

@ -1,150 +0,0 @@
# Signals: Skipping the Diff
In most cases, the traditional VirtualDOM diffing pattern is plenty fast. Dioxus will compare trees of VNodes, find the differences, and then update the Renderer's DOM with the diffs. However, this can generate a lot of overhead for certain types of components. In apps where reducing visual latency is a top priority, you can opt into the `Signals` api to entirely disable diffing of hot-path components. Dioxus will then automatically construct a state machine for your component, making updates nearly instant.
Signals build on the same infrastructure that powers asynchronous rendering where in-tree values can be updated outside of the render phase. In async rendering, a future is used as the signal source. With the raw signal API, any value can be used as a signal source.
By default, Dioxus will only try to diff subtrees of components with dynamic content, automatically skipping diffing static content.
## What does this look like?
Your component today might look something like this:
```rust, no_run
fn Comp(cx: Scope) -> DomTree {
let (title, set_title) = use_state(cx, || "Title".to_string());
cx.render(rsx!{
input {
value: title,
onchange: move |new| set_title(new.value())
}
})
}
```
This component is fairly straightforward – the input updates its own value on every change. However, every call to set_title will re-render the component. If we add a large list, then every time we update the title input, Dioxus will need to diff the entire list, over, and over, and over. This is **a lot** of wasted clock-cycles!
```rust, no_run
fn Comp(cx: Scope) -> DomTree {
let (title, set_title) = use_state(cx, || "Title".to_string());
cx.render(rsx!{
div {
input {
value: title,
onchange: move |new| set_title(new.value())
}
ul {
{0..10000.map(|f| rsx!{
li { "{f}" }
})}
}
}
})
}
```
Many experienced React developers will just say "this is bad design" – but we consider it to be a pit of failure, rather than a pit of success! That's why signals exist – to push you in a more performant (and ergonomic) direction. Signals let us directly bind values to their final place in the VirtualDOM. Whenever the signal value is updated, Dioxus will only the DOM nodes where that signal is used. Signals are built into Dioxus, so we can directly bind attributes of elements to their updates.
We can use signals to generate a two-way binding between data and the input box. Our text input is now just a two-line component!
```rust, no_run
fn Comp(cx: Scope) -> DomTree {
let mut title = use_signal(cx, || String::from("Title"));
cx.render(rsx!(input { value: title }))
}
```
For a slightly more interesting example, this component calculates the sum between two numbers, but totally skips the diffing process.
```rust, no_run
fn Calculator(cx: Scope) -> DomTree {
let mut a = use_signal(cx, || 0);
let mut b = use_signal(cx, || 0);
let mut c = a + b;
rsx! {
input { value: a }
input { value: b }
p { "a + b = {c}" }
}
}
```
Do you notice how we can use built-in operations on signals? Under the hood, we actually create a new derived signal that depends on `a` and `b`. Whenever `a` or `b` update, then `c` will update. If we need to create a new derived signal that's more complex than a basic operation (`std::ops`) we can either chain signals together or combine them:
```rust, no_run
let mut a = use_signal(cx, || 0);
let mut b = use_signal(cx, || 0);
// Chain signals together using the `with` method
let c = a.with(b).map(|(a, b)| *a + *b);
```
## Deref and DerefMut
If we ever need to get the value out of a signal, we can simply `deref` it.
```rust, no_run
let mut a = use_signal(cx, || 0);
let c = *a + *b;
```
Calling `deref` or `deref_mut` is actually more complex than it seems. When a value is derefed, you're essentially telling Dioxus that _this_ element _needs_ to be subscribed to the signal. If a signal is derefed outside of an element, the entire component will be subscribed and the advantage of skipping diffing will be lost. Dioxus will throw an error in the console when this happens to tell you that you're using signals wrong, but your component will continue to work.
## Global Signals
Sometimes you want a signal to propagate across your app, either through far-away siblings or through deeply-nested components. In these cases, we use Dirac: Dioxus's first-class state management toolkit. Dirac atoms automatically implement the Signal API. This component will bind the input element to the `TITLE` atom.
```rust, no_run
const TITLE: Atom<String> = Atom(|| "".to_string());
const Provider: Component = |cx|{
let title = use_signal(cx, &TITLE);
render!(input { value: title })
};
```
If we use the `TITLE` atom in another component, we can cause updates to flow between components without calling render or diffing either component trees:
```rust, no_run
const Receiver: Component = |cx|{
let title = use_signal(cx, &TITLE);
log::info!("This will only be called once!");
rsx!(cx,
div {
h1 { "{title}" }
div {}
footer {}
}
)
};
```
Dioxus knows that the receiver's `title` signal is used only in the text node, and skips diffing Receiver entirely, knowing to update _just_ the text node.
If you build a complex app on top of Dirac, you'll likely notice that many of your components simply won't be diffed at all. For instance, our Receiver component will never be diffed once it has been mounted!
## Signals and Iterators
Sometimes you want to use a collection of items. With Signals, you can bypass diffing for collections – a very powerful technique to avoid re-rendering on large collections.
By default, Dioxus is limited when you use iter/map. With the `For` component, you can provide an iterator and a function for the iterator to map to.
Dioxus automatically understands how to use your signals when mixed with iterators through `Deref`/`DerefMut`. This lets you efficiently map collections while avoiding the re-rendering of lists. In essence, signals act as a hint to Dioxus on how to avoid un-necessary checks and renders, making your app faster.
```rust, no_run
const DICT: AtomFamily<String, String> = AtomFamily(|_| {});
const List: Component = |cx|{
let dict = use_signal(cx, &DICT);
cx.render(rsx!(
ul {
For { each: dict, map: |k, v| rsx!( li { "{v}" }) }
}
))
};
```
## How does it work?
Signals internally use Dioxus' asynchronous rendering infrastructure to perform updates out of the tree.

52
docs/guide/src/en/__unused/advanced-guides/13-subtrees.md
View file

@ -1,52 +0,0 @@
# Subtrees
One way of extending the Dioxus VirtualDom is through the use of "Subtrees." Subtrees are chunks of the VirtualDom tree distinct from the rest of the tree. They still participate in event bubbling, diffing, etc, but will have a separate set of edits generated during the diff phase.
For a VirtualDom that has a root tree with two subtrees, the edits follow a pattern of:
Root
-> Tree 1
-> Tree 2
-> Original root tree
- Root edits
- Tree 1 Edits
- Tree 2 Edits
- Root Edits
The goal of this functionality is to enable things like Portals, Windows, and inline alternative renderers without needing to spin up a new VirtualDom.
With the right renderer plugins, a subtree could be rendered as anything – a 3D scene, SVG, or even as the contents of a new window or modal. This functionality is similar to "Portals" in React, but much more "renderer agnostic." Portals, by nature, are not necessarily cross-platform and rely on renderer functionality, so it makes sense to abstract their purpose into the subtree concept.
The desktop renderer comes pre-loaded with the window and notification subtree plugins, making it possible to render subtrees into entirely different windows.
Subtrees also solve the "bridging" issues in React where two different renderers need two different VirtualDoms to work properly. In Dioxus, you only ever need one VirtualDom and the right renderer plugins.
## API
Due to their importance in the hierarchy, Components – not nodes – are treated as subtree roots.
```rust, no_run
fn Subtree<P>(cx: Scope<P>) -> DomTree {
}
fn Window() -> DomTree {
Subtree {
onassign: move |e| {
// create window
}
children()
}
}
fn 3dRenderer -> DomTree {
Subtree {
onassign: move |e| {
// initialize bevy
}
}
}
```

280
docs/guide/src/en/__unused/advanced-guides/custom-renderer.md
View file

@ -1,280 +0,0 @@
# Custom Renderer
Dioxus is an incredibly portable framework for UI development. The lessons, knowledge, hooks, and components you acquire over time can always be used for future projects. However, sometimes those projects cannot leverage a supported renderer or you need to implement your own better renderer.
Great news: the design of the renderer is entirely up to you! We provide suggestions and inspiration with the 1st party renderers, but only really require implementation of the `RealDom` trait for things to function properly.
## The specifics:
Implementing the renderer is fairly straightforward. The renderer needs to:
1. Handle the stream of edits generated by updates to the virtual DOM
2. Register listeners and pass events into the virtual DOM's event system
3. Progress the virtual DOM with an async executor (or disable the suspense API and use `progress_sync`)
Essentially, your renderer needs to implement the `RealDom` trait and generate `EventTrigger` objects to update the VirtualDOM. From there, you'll have everything needed to render the VirtualDOM to the screen.
Internally, Dioxus handles the tree relationship, diffing, memory management, and the event system, leaving as little as possible required for renderers to implement themselves.
For reference, check out the WebSys renderer as a starting point for your custom renderer.
## Trait implementation and DomEdits
The current `RealDom` trait lives in `dioxus-core/diff`. A version of it is provided here (but might not be up-to-date):
```rust, no_run
pub trait RealDom<'a> {
fn handle_edit(&mut self, edit: DomEdit);
fn request_available_node(&mut self) -> ElementId;
fn raw_node_as_any(&self) -> &mut dyn Any;
}
```
For reference, the "DomEdit" type is a serialized enum that represents an atomic operation occurring on the RealDom. The variants roughly follow this set:
```rust, no_run
enum DomEdit {
PushRoot,
AppendChildren,
ReplaceWith,
CreateTextNode,
CreateElement,
CreateElementNs,
CreatePlaceholder,
NewEventListener,
RemoveEventListener,
SetText,
SetAttribute,
RemoveAttribute,
}
```
The Dioxus diffing mechanism operates as a [stack machine](https://en.wikipedia.org/wiki/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.
### An example
For the sake of understanding, lets consider this example – a very simple UI declaration:
```rust, no_run
rsx!( h1 {"hello world"} )
```
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 `PushRoot` where the ID of the root is the container.
When the renderer receives this instruction, it pushes the actual Node onto its own stack. The real renderer's stack will look like this:
```rust, no_run
instructions: [
PushRoot(Container)
]
stack: [
ContainerNode,
]
```
Next, Dioxus will encounter the h1 node. The diff algorithm decides that this node needs to be created, so Dioxus will generate the DomEdit `CreateElement`. When the renderer receives this instruction, it will create an unmounted node and push into its own stack:
```rust, no_run
instructions: [
PushRoot(Container),
CreateElement(h1),
]
stack: [
ContainerNode,
h1,
]
```
Next, Dioxus sees the text node, and generates the `CreateTextNode` DomEdit:
```rust, no_run
instructions: [
PushRoot(Container),
CreateElement(h1),
CreateTextNode("hello world")
]
stack: [
ContainerNode,
h1,
"hello world"
]
```
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 `AppendChildren`. This pops the text node off the stack, leaving the h1 element as the next element in line.
```rust, no_run
instructions: [
PushRoot(Container),
CreateElement(h1),
CreateTextNode("hello world"),
AppendChildren(1)
]
stack: [
ContainerNode,
h1
]
```
We call `AppendChildren` again, popping off the h1 node and attaching it to the parent:
```rust, no_run
instructions: [
PushRoot(Container),
CreateElement(h1),
CreateTextNode("hello world"),
AppendChildren(1),
AppendChildren(1)
]
stack: [
ContainerNode,
]
```
Finally, the container is popped since we don't need it anymore.
```rust, no_run
instructions: [
PushRoot(Container),
CreateElement(h1),
CreateTextNode("hello world"),
AppendChildren(1),
AppendChildren(1),
Pop(1)
]
stack: []
```
Over time, our stack looked like this:
```rust, no_run
[]
[Container]
[Container, h1]
[Container, h1, "hello world"]
[Container, h1]
[Container]
[]
```
Notice how our stack is empty once UI has been mounted. Conveniently, this approach completely separates the VirtualDOM 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 makes Dioxus independent of platform specifics.
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.
It's important to note that there _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.
Whenever a `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 doesn't reclaim IDs of elements its removed, but your renderer probably will want to. To do this, we suggest using a `SecondarySlotMap` if implementing the renderer in Rust, or just deferring to a HashMap-type approach.
This little demo serves to show exactly how a Renderer would need to process an edit stream to build UIs. A set of serialized EditStreams for various demos is available for you to test your custom renderer against.
## Event loop
Like most GUIs, Dioxus relies on an event loop to progress the VirtualDOM. The VirtualDOM itself can produce events as well, so it's important that your custom renderer can handle those too.
The code for the WebSys implementation is straightforward, so we'll add it here to demonstrate how simple an event loop is:
```rust, no_run
pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
// Push the body element onto the WebsysDom's stack machine
let mut websys_dom = crate::new::WebsysDom::new(prepare_websys_dom());
websys_dom.stack.push(root_node);
// Rebuild or hydrate the virtualdom
self.internal_dom.rebuild(&mut websys_dom)?;
// Wait for updates from the real dom and progress the virtual dom
loop {
let user_input_future = websys_dom.wait_for_event();
let internal_event_future = self.internal_dom.wait_for_event();
match select(user_input_future, internal_event_future).await {
Either::Left((trigger, _)) => trigger,
Either::Right((trigger, _)) => trigger,
}
}
while let Some(trigger) = {
websys_dom.stack.push(body_element.first_child().unwrap());
self.internal_dom
.progress_with_event(&mut websys_dom, trigger)?;
}
}
```
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 `VirtualEvent` type. Your custom event must implement the corresponding event trait. Right now, the VirtualEvent system is modeled almost entirely around the HTML spec, but we are interested in slimming it down.
```rust, no_run
fn virtual_event_from_websys_event(event: &web_sys::Event) -> VirtualEvent {
match event.type_().as_str() {
"keydown" | "keypress" | "keyup" => {
struct CustomKeyboardEvent(web_sys::KeyboardEvent);
impl dioxus::events::KeyboardEvent for CustomKeyboardEvent {
fn char_code(&self) -> usize { self.0.char_code() }
fn ctrl_key(&self) -> bool { self.0.ctrl_key() }
fn key(&self) -> String { self.0.key() }
fn key_code(&self) -> usize { self.0.key_code() }
fn location(&self) -> usize { self.0.location() }
fn meta_key(&self) -> bool { self.0.meta_key() }
fn repeat(&self) -> bool { self.0.repeat() }
fn shift_key(&self) -> bool { self.0.shift_key() }
fn which(&self) -> usize { self.0.which() }
fn get_modifier_state(&self, key_code: usize) -> bool { self.0.get_modifier_state() }
}
VirtualEvent::KeyboardEvent(Rc::new(event.clone().dyn_into().unwrap()))
}
_ => todo!()
```
## Custom raw elements
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.
These custom elements are defined as unit structs with trait implementations.
For example, the `div` element is (approximately!) defined as such:
```rust, no_run
struct div;
impl div {
/// Some glorious documentation about the class property.
#[inline]
fn class<'a>(&self, cx: NodeFactory<'a>, val: Arguments) -> Attribute<'a> {
cx.attr("class", val, None, false)
}
// more attributes
}
```
You've probably noticed that many elements in the `rsx!` and `html!` 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.
## Compatibility
Forewarning: not every hook and service will work on your platform. Dioxus wraps things that need to be cross-platform in "synthetic" types. However, downcasting to a native type might fail if the types don't match.
There are three opportunities for platform incompatibilities to break your program:
1. When downcasting elements via `Ref.downcast_ref<T>()`
2. When downcasting events via `Event.downcast_ref<T>()`
3. Calling platform-specific APIs that don't exist
The best hooks will properly detect the target platform and still provide functionality, failing gracefully when a platform is not supported. We encourage – and provide – an indication to the user on what platforms a hook supports. For issues 1 and 2, these return a result as to not cause panics on unsupported platforms. When designing your hooks, we recommend propagating this error upwards into user facing code, making it obvious that this particular service is not supported.
This particular code _will panic_ due to the unwrap on downcast_ref. Try to avoid these types of patterns.
```rust, no_run
let div_ref = use_node_ref(cx);
cx.render(rsx!{
div { ref: div_ref, class: "custom class",
button { "click me to see my parent's class"
onclick: move |_| if let Some(div_ref) = div_ref {
log::info!("Div class is {}", div_ref.downcast_ref::<web_sys::Element>().unwrap().class())
}
}
}
})
```
## Conclusion
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 renderer, video game UI, and even augmented reality! If you're interesting in contributing to any of the these projects, don't be afraid to reach out or join the community.

32
docs/guide/src/en/__unused/advanced-guides/liveview.md
View file

@ -1,32 +0,0 @@
# Dioxus Liveview
Liveview is a configuration where a server and a client work together to render a Dioxus app. Liveview monomorphizes a web application, eliminating the need for frontend-specific APIs.
This is a developer-friendly alternative to the JAM-stack (Javascript + API + Markdown), combining the Wasm-compatibility and async performance of Rust.
## Why liveview?
### No APIs necessary!
Because Liveview combines the server and the client, you'll find dedicated APIs unnecessary. You'll still want to implement a data-fetching service for Live-apps, but this can be implemented as a crate and shared between apps. This approach was designed to let you model out your data requirements without needing to maintain a public versioned API.
You can find more information to data modeling and fetching for LiveApps in the "Book of Dioxus Patterns".
### Ease of deployment
There is no hassle for deploying Dioxus liveview apps – simply upload the binary to your hosting provider of choice. There simply is no need to deal with intermediate APIs. An app's frontend and backend are tightly coupled to each other, meaning that the backed and frontend are always up to date.
This is especially powerful for small teams, where fast iteration, versioned unique prototypes, and simple deployments are important. As your app grows, Dioxus will happily grow with you, serving up to 100K RPS (thanks to async Rust performance).
### Power of server rendering combined with the reactive nature of JavaScript
Liveview apps are backed by a server and enhanced with web-assembly. This completely eliminates the need to write Javascript to add dynamic content to webpages. Apps are written in only **one** language and require essentially 0 knowledge of build systems, transpiling or ECMAScript versions. Minimum browser support is guaranteed to cover 95% of users, and the Dioxus-CLI can be configured to generate polyfills for even more support.
### Support with LiveHost by Dioxus-Labs
The Dioxus-CLI comes ready for use with premium Dioxus-Labs services, like LiveHost. Simply link up your git repo to the Dioxus LiveHost and start deploying your fullstack Dioxus app today. LiveHost supports:
- Versioned fronted/backend with unique links
- Builtin CI/CD
- Managed and pluggable storage database backends
- Serverless support for minimal latency
- Site Analytics
- Lighthouse optimization
- On-premise support (see license terms)
Dioxus LiveHost is a Dioxus LiveApp management service with all supported features in a single binary. For OSS, we permit free usage and deployment of LiveHost to your favorite hosting provider.

67
docs/guide/src/en/__unused/advanced-guides/rsx.md
View file

@ -1,67 +0,0 @@
# VNodes with RSX, HTML, and NodeFactory
Many modern frameworks provide a domain-specific-language for declaring user-interfaces. In the case of React, this language extension is called JSX and must be handled through additional dependencies and pre/post processors to transform your source code. With Rust, we can simply provide a procedural macro in the Dioxus dependency itself that mimics the JSX language.
With Dioxus, we actually ship two different macros – a macro that mimics JSX (the `html!` macro) and a macro that mimics Rust's native nested-struct syntax (the `rsx!` macro). These macros simply transform their inputs into NodeFactory calls.
For instance, this html! call:
```rust, no_run
html!(<div> "hello world" </div>)
```
becomes this NodeFactory call:
```rust, no_run
|f| f.element(
dioxus_elements::div, // tag
[], // listeners
[], // attributes
[f.static_text("hello world")], // children
None // key
)
```
The NodeFactory API is fairly ergonomic, making it a viable option to use directly. The NodeFactory API is also compile-time correct and has incredible syntax highlighting support. We use what Rust calls a "unit type" – the `dioxus_elements::div` and associated methods to ensure that a `div` can only have attributes associated with `div`s. This lets us tack on relevant documentation, autocomplete support, and jump-to-definition for methods and attributes.
![Compile time correct syntax](../images/compiletimecorrect.png)
## html! macro
The html! macro supports a limited subset of the html standard. Rust's macro parsing tools are somewhat limited, so all text between tags _must be quoted_.
However, writing HTML by hand is a bit tedious – IDE tools for Rust don't support linting/autocomplete/syntax highlighting. We suggest using RSX – it's more natural for Rust programs and _does_ integrate well with Rust IDE tools.
```rust, no_run
let name = "jane";
let pending = false;
let count = 10;
dioxus::ssr::render_lazy(html! {
<div>
<p> "Hello, {name}!" </p>
<p> "Status: {pending}!" </p>
<p> "Count {count}!" </p>
</div>
});
```
## rsx! macro
The rsx! macro is a VNode builder macro designed especially for Rust programs. Writing these should feel very natural, much like assembling a struct. VSCode also supports these with code folding, bracket-tabbing, bracket highlighting, section selecting, inline documentation, GOTO definition, and refactoring support.
When helpful, the Dioxus VSCode extension provides a way of converting a selection of HTML directly to RSX, so you can import templates from the web directly into your existing app.
It's also a bit easier on the eyes than HTML.
```rust, no_run
dioxus::ssr::render_lazy(rsx! {
div {
p {"Hello, {name}!"}
p {"Status: {pending}!"}
p {"Count {count}!"}
}
});
```
In the next section, we'll cover the `rsx!` macro in more depth.

29
docs/guide/src/en/__unused/advanced-guides/testing.md
View file

@ -1,29 +0,0 @@
## Testing
To test your Rust code, you can annotate any function with the `#[test]` block. In VSCode with RA, this will provide a lens to click and run the test.
```rust, no_run
#[test]
fn component_runs() {
assert!(true)
}
```
This will test your Rust code _without_ going through the browser. This is ideal for squashing logic bugs and ensuring components render appropriately when the browsers's DOM is not needed. If you need to run tests in the browser, you can annotate your blocks with the `#[dioxus::test]` block.
```rust, no_run
#[dioxus::test]
fn runs_in_browser() {
// ...
}
```
Then, when you run
```console
dx test --chrome
```
Dioxus will build and test your code using the Chrome browser as a harness.
There's a lot more to testing if you dive in, so check out the [Testing]() guide for more information

30
docs/guide/src/en/__unused/attribute_spreading.md
View file

@ -1,30 +0,0 @@
In the cases where you need to pass arbitrary element properties into a component – say to add more functionality to the `<a>` tag, Dioxus will accept any quoted fields. This is similar to adding arbitrary fields to regular elements using quotes.
```rust, no_run
rsx!(
Clickable {
"class": "blue-button",
"style": "background: red;"
}
)
```
For a component to accept these attributes, you must add an `attributes` field to your component's properties. We can use the spread syntax to add these attributes to whatever nodes are in our component.
```rust, no_run
#[derive(Props)]
struct ClickableProps<'a> {
attributes: Attributes<'a>
}
fn clickable(cx: Scope<ClickableProps<'a>>) -> Element {
cx.render(rsx!(
a {
..cx.props.attributes,
"Any link, anywhere"
}
))
}
```

244
docs/guide/src/en/__unused/composing.md
View file

@ -1,244 +0,0 @@
# Thinking in Reactively
We've finally reached the point in our tutorial where we can talk about the theory of Reactivity. We've talked about defining a declarative view, but not about the aspects that make our code _reactive_.
Understanding the theory of reactive programming is essential to making sense of Dioxus and writing effective, performant UIs.
In this section, we'll talk about:
- One-way data flow
- Modifying data
- Forcing renders
- How renders propagate
This section is a bit long, but worth the read. We recommend coffee, tea, and/or snacks.
## Reactive Programming
Dioxus is one of a handful of Rust libraries that provide a "Reactive Programming Model". The term "Reactive programming" is a classification of programming paradigm – much like functional or imperative programming. This is a very important distinction since it affects how we _think_ about our code.
Reactive programming is a programming model concerned with deriving computations from asynchronous data flow. Most reactive programs are comprised of datasources, intermediate computations, and a final result.
We consider the rendered GUI to be the final result of our Dioxus apps. The datasources for our apps include local and global state.
For example, the model presented in the figure below is comprised of two data sources: time and a constant. These values are passed through our computation graph to achieve a final result: `g`.
![Reactive Model](https://upload.wikimedia.org/wikipedia/commons/thumb/e/e9/Reactive_programming_glitches.svg/440px-Reactive_programming_glitches.svg.png)
Whenever our `seconds` variable changes, we will then reevaluate the computation for `t`. Because `g` relies on `t`, we will also reevaluate its computation too. Notice that we would've reevaluated the computation for `g` even if `t` didn't change because `seconds` is used to calculate `g`.
However, if we somehow changed our constant from `1` to `2`, then we need to reevaluate `t`. If, for whatever reason, this change did not affect the result of `t`, then we wouldn't try to reevaluate `g`.
In Reactive Programming, we don't think about whether or not we should reevaluate `t` or `g`; instead, we simply provide functions of computation and let the framework figure out the rest for us.
In Rust, our reactive app would look something like:
```rust, no_run
fn compute_g(t: i32, seconds: i32) -> bool {
t > seconds
}
fn compute_t(constant: i32, seconds: i32) -> i32 {
constant + seconds
}
fn compute_graph(constant: i32, seconds: i32) -> bool {
let t = compute_t(constant, seconds);
let g = compute_g(t, seconds);
g
}
```
## How is Dioxus Reactive?
The Dioxus VirtualDom provides us a framework for reactive programming. When we build apps with dioxus, we need to provide our own datasources. This can be either initial props or some values fetched from the network. We then pass this data through our app into components through properties.
If we represented the reactive graph presented above in Dioxus, it would look very similar:
```rust, no_run
// Declare a component that holds our datasources and calculates `g`
fn RenderGraph(cx: Scope) -> Element {
let seconds = use_datasource(SECONDS);
let constant = use_state(cx, || 1);
cx.render(rsx!(
RenderG { seconds: seconds }
RenderT { seconds: seconds, constant: constant }
))
}
// "calculate" g by rendering `t` and `seconds`
#[inline_props]
fn RenderG(cx: Scope, seconds: i32) -> Element {
cx.render(rsx!{ "There are {seconds} seconds remaining..." })
}
// calculate and render `t` in its own component
#[inline_props]
fn RenderT(cx: Scope, seconds: i32, constant: i32) -> Element {
let res = seconds + constant;
cx.render(rsx!{ "{res}" })
}
```
With this app, we've defined three components. Our top-level component provides our datasources (the hooks), computation nodes (child components), and a final value (what's "rendered").
Now, whenever the `constant` changes, our `RenderT` component will be re-rendered. However, if `seconds` doesn't change, then we don't need to re-render `RenderG` because the input is the same. If `seconds` _does_ change, then both RenderG and RenderT will be reevaluated.
Dioxus is "Reactive" because it provides this framework for us. All we need to do is write our own tiny units of computation and Dioxus figures out which components need to be reevaluated automatically.
These extra checks and algorithms add some overhead, which is why you see projects like [Sycamore](http://sycamore-rs.netlify.app) and [SolidJS](http://solidjs.com) eliminating them altogether. Dioxus is _really_ fast, so we're willing to exchange the added overhead for improved developer experience.
## How do we update values in our dataflow graph?
Dioxus will automatically figure out how to regenerate parts of our app when datasources change. But how exactly can we update our data sources?
In Dioxus there are two datasources:
1. Local state in `use_hook` and all other hooks
2. Global state through `provide_context`.
Technically, the root props of the VirtualDom are a third datasource, but since we cannot modify them, they are not worth talking about.
### Local State
For local state in hooks, Dioxus gives us the `use_hook` method which returns an `&mut T` without any requirements. This means raw hook values are not tracked by Dioxus. In fact, we could write a component that modifies a hook value directly:
```rust, no_run
fn app(cx: Scope) -> Element {
let mut count = cx.use_hook(|_| 0);
cx.render(rsx!{
button {
onclick: move |_| *count += 1,
"Count: {count}"
}
})
}
```
However, when this value is written to, the component does not know to be reevaluated. We must explicitly tell Dioxus that this component is "dirty" and needs to be re-rendered. This is done through the `cx.needs_update` method:
```rust, no_run
button {
onclick: move |_| {
*count += 1;
cx.needs_update();
},
"Count: {count}"
}
```
Now, whenever we click the button, the value will change and the component will be re-rendered.
> Re-rendering is when Dioxus calls your function component _again_. Component functions will be called over and over throughout their lifetime, so they should be mostly side-effect free.
### Understand this!
Your component functions will be called ("rendered" in our lingo) for as long as the component is present in the tree.
A single component will be called multiple times, modifying its own internal state or rendering new nodes with new values from its properties.
### App-Global State
With the `provide_context` and `consume_context` methods on `Scope`, we can share values to descendants without having to pass values through component props. This has the side-effect of making our datasources less obvious from a high-level perspective, but it makes our components more modular within the same codebase.
To make app-global state easier to reason about, Dioxus makes all values provided through `provide_context` immutable. This means any library built on top of `provide_context` needs to use interior mutability to modify shared global state.
In these cases, App-Global state needs to manually track which components need to be re-generated.
To regenerate _any_ component in your app, you can get a handle to the Dioxus' internal scheduler through `schedule_update_any`:
```rust, no_run
let force_render = cx.schedule_update_any();
// force a render of the root component
force_render(ScopeId(0));
```
## What does it mean for a component to "re-render"?
In our guides, we frequently use the phrase "re-render" to describe updates to our app. You'll often hear this paired with "preventing unnecessary re-renders." But what exactly does this mean?
When we call `dioxus::desktop::launch`, Dioxus will create a new `Scope` object and call the component we gave it. Our `rsx!` calls will create new nodes which we return back to the VirtualDom. Dioxus will then look through these nodes for child components, call their functions, and so on until every component has been "rendered." We consider these nodes "rendered" because they were created because of our explicit actions.
The tree of UI that dioxus creates will roughly look like the tree of components presented earlier:
![Tree of UI](../images/component_tree.png)
But what happens when we call `needs_update` after modifying some important state? Well, if Dioxus called our component's function again, then we would produce new, different nodes. In fact, this is exactly what Dioxus does!
At this point, we have some old nodes and some new nodes. Again, we call this "rendering" because Dioxus had to create new nodes because of our explicit actions. Any time new nodes get created, our VirtualDom is being "rendered."
These nodes are stored in an extremely efficient memory allocator called a "bump arena." For example, a div with a handler and attribute would be stored in memory in two locations: the "old" tree and the "new" tree.
![Bump Arenas](../images/oldnew.png)
From here, Dioxus computes the difference between these trees and updates the Real DOM to make it look like the new version of what we've declared.
![Diffing](../images/diffing.png)
## Suppressing Renders
So, we know how to make Dioxus render, but how do we _stop_ it? What if we _know_ that our state didn't change and we shouldn't render and diff new nodes because they'll be exactly the same as the last time?
In these cases, you want to reach for _memoization_. In Dioxus, memoization involves preventing a component from rendering again if its props didn't change since the last time it attempted to render.
Visually, you can tell that a component will only re-render if the new value is sufficiently different than the old one.
| props.val | re-render |
| --------- | --------- |
| 10 | true |
| 20 | true |
| 20 | false |
| 20 | false |
| 10 | true |
| 30 | false |
This is why when you `derive(Props)`, you must also implement the `PartialEq` trait. To override the memoization strategy for a component, you can simply implement your own PartialEq.
```rust, no_run
struct CustomProps {
val: i32,
}
impl PartialEq for CustomProps {
fn partial_eq(&self, other: &Self) -> bool {
// we don't render components that have a val less than 5
if other.val > 5 && self.val > 5{
self.val == other.val
}
}
}
```
However, for components that borrow data, it doesn't make sense to implement PartialEq since the actual references in memory might be different.
You can technically override this behavior by implementing the `Props` trait manually, though it's unsafe and easy to mess up:
```rust, no_run
unsafe impl Properties for CustomProps {
fn memoize(&self, other &Self) -> bool {
self != other
}
}
```
TLDR:
- Dioxus checks if props changed between renders
- If props changed according to PartialEq, Dioxus re-renders the component
- Props that have a lifetime (ie `<'a>`) will always be re-rendered
## Wrapping Up
Wow, that was a lot of material!
Let's see if we can recap what was presented:
- Reactive programming calculates a final value from datasources and computation
- Dioxus is "reactive" since it figures out which computations to check
- `schedule_update` must be called to mark a component as dirty
- dirty components will be re-rendered (called multiple times) to produce a new UI
- Renders can be suppressed with memoization
This theory is crucial to understand how to compose components and how to control renders in your app.

26
docs/guide/src/en/__unused/event_javascript.rs
View file

@ -1,26 +0,0 @@
## JavaScript Handlers
Instead of passing a closure, you can also pass a string to event handlers – this lets you use JavaScript (if your renderer can execute JavaScript):
```rust
{{#include ../../../examples/event_javascript.rs:rsx}}
```
#![allow(non_snake_case)]
use dioxus::prelude::*;
fn main() {
dioxus::desktop::launch(App);
}
fn App(cx: Scope) -> Element {
cx.render(rsx! {
// ANCHOR: rsx
div {
onclick: "alert('hello world')",
}
// ANCHOR_END: rsx
})
}

61
docs/guide/src/en/__unused/fanout.md
View file

@ -1,61 +0,0 @@
# Fanning Out
One of the most reliable state management patterns in large Dioxus apps is `fan-out`. The fan-out pattern is the ideal way to structure your app to maximize code reuse, testability, and deterministic rendering.
## The structure
With `fan-out`, our individual components at "leaf" position of our VirtualDom are "pure", making them easily reusable, testable, and deterministic. For instance, the "title" bar of our app might be a fairly complicated component.
```rust, no_run
#[derive(Props, PartialEq)]
struct TitlebarProps {
title: String,
subtitle: String,
}
fn Titlebar(cx: Scope<TitlebarProps>) -> Element {
cx.render(rsx!{
div {
class: "titlebar"
h1 { "{cx.props.title}" }
h1 { "{cx.props.subtitle}" }
}
})
}
```
If we used global state like use_context or fermi, we might be tempted to inject our `use_read` directly into the component.
```rust, no_run
fn Titlebar(cx: Scope<TitlebarProps>) -> Element {
let title = use_read(cx, TITLE);
let subtitle = use_read(cx, SUBTITLE);
cx.render(rsx!{/* ui */})
}
```
For many apps – this is a fine pattern, especially if the component is a one-off. However, if we want to reuse the component outside of this app, then we'll start to run into issues where our contexts are unavailable.
## Fanning Out
To enable our titlebar component to be used across apps, we want to lift our atoms upwards and out of the Titlebar component. We would organize a bunch of other components in this section of the app to share some of the same state.
```rust, no_run
fn DocsiteTitlesection(cx: Scope) {
let title = use_read(cx, TITLE);
let subtitle = use_read(cx, SUBTITLE);
let username = use_read(cx, USERNAME);
let points = use_read(cx, POINTS);
cx.render(rsx!{
TitleBar { title: title, subtitle: subtitle }
UserBar { username: username, points: points }
})
}
```
This particular wrapper component unfortunately cannot be reused across apps. However, because it simply wraps other real elements, it doesn't have to. We are free to reuse our TitleBar and UserBar components across apps with ease. We also know that this particular component is plenty performant because the wrapper doesn't have any props and is always memoized. The only times this component re-renders is when any of the atoms change.
This is the beauty of Dioxus – we always know where our components are likely to be re-rendered. Our wrapper components can easily prevent any large re-renders by simply memoizing their components. This system might not be as elegant or precise as signal systems found in libraries like Sycamore or SolidJS, but it is quite ergonomic.

14
docs/guide/src/en/__unused/hello_world.md
View file

@ -1,14 +0,0 @@
# "Hello, World" desktop app
If you plan to develop extensions for the `Dioxus` ecosystem, please use the `dioxus` crate with the `core` feature to limit the amount of dependencies your project brings in.
### What is this `Scope` object?
Coming from React, the `Scope` object might be confusing. In React, you'll want to store data between renders with hooks. However, hooks rely on global variables which make them difficult to integrate in multi-tenant systems like server-rendering.
In Dioxus, you are given an explicit `Scope` object to control how the component renders and stores data. The `Scope` object provides a handful of useful APIs for features like suspense, rendering, and more.
For now, just know that `Scope` lets you store state with hooks and render elements with `cx.render`.

47
docs/guide/src/en/__unused/helpers.md
View file

@ -1,47 +0,0 @@
# Helper Crates
Because the Dioxus ecosystem is fairly young, there aren't a ton of third-party libraries designed to "get things done." That's where the Dioxus helper crates come in. These are officially supported crates built on top of existing libraries to solve some of the common barriers to building apps.
## Router
Quickly add a cross-platform router to structure your app.
[Link](https://github.com/DioxusLabs/dioxus/tree/master/packages/router)
## Fermi
Global state as easy as `use_state`.
[Link](https://github.com/DioxusLabs/dioxus/tree/master/packages/fermi)
## Query
This crate has yet to be developed! However, we do plan on providing a crate for good fetching and query support.
## 3rd-party – Toast
Toast notifications, curtesy of [@mrxiaozhuox](https://github.com/mrxiaozhuox).
[Link](https://github.com/mrxiaozhuox/dioxus-toast)
## 3rd-party – HeroIcon
Collection of helpful hero icons, curtesy of [@autarch](https://github.com/autarch).
[Link](https://github.com/houseabsolute/dioxus-heroicons)
## 3rd-party – Katex
Draw beautiful equations, curtesy of [@oovm](https://github.com/oovm)
[Link](https://github.com/oovm/katex-wasm/tree/dev/projects/dioxus-katex)
## 3rd-party – PrimsJS
Highlight your code blocks with ease, curtesy of [@oovm](https://github.com/oovm)
[Link](https://github.com/oovm/katex-wasm/tree/dev/projects/dioxus-katex)

36
docs/guide/src/en/__unused/index.md
View file

@ -1,36 +0,0 @@
# Managing State
Every app you'll build with Dioxus will have some sort of state that needs to be maintained and updated as your users interact with it. However, managing state can be particularly challenging at times, and is frequently the source of bugs in many GUI frameworks.
In this chapter, we'll cover the various ways to manage state, the appropriate terminology, various patterns, and some problems you might run into.
## The Problem
Why do people say state management is so difficult? What does it mean?
Generally, state management is the code you need to write to ensure that your app renders the _correct_ content. If the user inputs a name, then you need to display the appropriate response – like alerts, validation, and disable/enable various elements on the page. Things can quickly become tricky if you need loading screens and cancellable tasks.
For the simplest of apps, all of your state can enter the app from the root props. This is common in server-side rendering – we can collect all of the required state _before_ rendering the content.
```rust, no_run
let all_content = get_all_content().await;
let output = dioxus::ssr::render_lazy(rsx!{
div {
RenderContent { content: all_content }
}
});
```
With this incredibly simple setup, it is highly unlikely that you'll have rendering bugs. There simply is barely any state to manage.
However, most of your apps will store state inside of the Dioxus VirtualDom – either through local state or global state.
## Your options
To deal with complexity, you have a couple of options:
- Refactor state out of shared state and into reusable components and hooks.
- Lift state upwards to be spread across multiple components (fan out).
- Use the Context API to share state globally.
- Use a dedicated state management solution like Fermi.

107
docs/guide/src/en/__unused/localstate.md
View file

@ -1,107 +0,0 @@
# Local State
The first step to dealing with complexity in your app is to refactor your state to be purely local. This encourages good code reuse and prevents leakage of abstractions across component boundaries.
## What it looks like
Let's say we're managing the state for a list of Todos. Whenever we edit the todo, we want the list to update. We might've started building our app but putting everything into a single `use_ref`.
```rust, no_run
struct Todo {
contents: String,
is_hovered: bool,
is_editing: bool,
}
let todos = use_ref(cx, || vec![Todo::new()]);
cx.render(rsx!{
ul {
todos.read().iter().enumerate().map(|(id, todo)| rsx!{
li {
onhover: move |_| *todos.write()[id].is_hovered = true,
h1 { "{todo.contents}" }
}
})
}
})
```
As shown above, whenever the todo is hovered, we want to set its state:
```rust, no_run
todos.write()[0].is_hovered = true;
```
As the amount of interactions goes up, so does the complexity of our state. Should the "hover" state really be baked into our data model?
Instead, let's refactor our Todo component to handle its own state:
```rust, no_run
#[inline_props]
fn Todo<'a>(cx: Scope, todo: &'a Todo) -> Element {
let is_hovered = use_state(cx, || false);
cx.render(rsx!{
li {
h1 { "{todo.contents}" }
onhover: move |_| is_hovered.set(true),
}
})
}
```
Now, we can simplify our Todo data model to get rid of local UI state:
```rust, no_run
struct Todo {
contents: String,
}
```
This is not only better for encapsulation and abstraction, but it's only more performant! Whenever a Todo is hovered, we won't need to re-render _every_ Todo again – only the Todo that's currently being hovered.
Wherever possible, you should try to refactor the "view" layer _out_ of your data model.
## Immutability
Storing all of your state inside a `use_ref` might be tempting. However, you'll quickly run into an issue where the `Ref` provided by `read()` "does not live long enough." An indeed – you can't return locally-borrowed value into the Dioxus tree.
In these scenarios consider breaking your `use_ref` into individual `use_state`s.
You might've started modeling your component with a struct and use_ref
```rust, no_run
struct State {
count: i32,
color: &'static str,
names: HashMap<String, String>
}
// in the component
let state = use_ref(cx, State::new)
```
The "better" approach for this particular component would be to break the state apart into different values:
```rust, no_run
let count = use_state(cx, || 0);
let color = use_state(cx, || "red");
let names = use_state(cx, HashMap::new);
```
You might recognize that our "names" value is a HashMap – which is not terribly cheap to clone every time we update its value. To solve this issue, we _highly_ suggest using a library like [`im`](https://crates.io/crates/im) which will take advantage of structural sharing to make clones and mutations much cheaper.
When combined with the `make_mut` method on `use_state`, you can get really succinct updates to collections:
```rust, no_run
let todos = use_state(cx, im_rc::HashMap::default);
todos.make_mut().insert("new todo", Todo {
contents: "go get groceries",
});
```
## Moving on
This particular local patterns are powerful but is not a cure-all for state management problems. Sometimes your state problems are much larger than just staying local to a component.

26
docs/guide/src/en/__unused/memoization.md
View file

@ -1,26 +0,0 @@
## Memoization
Dioxus uses Memoization for a more efficient user interface. Memoization is the process in which we check if a component actually needs to be re-rendered when its props change. If a component's properties change but they wouldn't affect the output, then we don't need to re-render the component, saving time!
For example, let's say we have a component that has two children:
```rust, no_run
fn Demo(cx: Scope) -> Element {
// don't worry about these 2, we'll cover them later
let name = use_state(cx, || String::from("bob"));
let age = use_state(cx, || 21);
cx.render(rsx!{
Name { name: name }
Age { age: age }
})
}
```
If `name` changes but `age` does not, then there is no reason to re-render our `Age` component since the contents of its props did not meaningfully change.
Dioxus memoizes owned components. It uses `PartialEq` to determine if a component needs rerendering, or if it has stayed the same. This is why you must derive PartialEq!
> This means you can always rely on props with `PartialEq` or no props at all to act as barriers in your app. This can be extremely useful when building larger apps where properties frequently change. By moving our state into a global state management solution, we can achieve precise, surgical re-renders, improving the performance of our app.
Borrowed Props cannot be safely memoized. However, this is not a problem – Dioxus relies on the memoization of their parents to determine if they need to be rerendered.

64
docs/guide/src/en/__unused/model_pattern.md
View file

@ -1,64 +0,0 @@
## Using UseRef with "models"
One option for state management that UseRef enables is the development of a "model" for your components. This particular pattern enables you to model your state with regular structs.
For instance, our calculator example uses a struct to model the state.
```rust, no_run
struct Calculator {
display_value: String,
operator: Option<Operator>,
waiting_for_operand: bool,
cur_val: f64,
}
```
Our component is really simple – we just call `use_ref` to get an initial calculator state.
```rust, no_run
fn app(cx: Scope) -> Element {
let state = use_ref(cx, Calculator::new);
cx.render(rsx!{
// the rendering code
})
}
```
In our UI, we can then use `read` and a helper method to get data out of the model.
```rust, no_run
// Our accessor method
impl Calculator {
fn formatted_display(&self) -> String {
self.display_value
.parse::<f64>()
.unwrap()
.separated_string()
}
}
// And then in the UI
cx.render(rsx!{
div { [state.read().formatted_display()] }
})
```
To modify the state, we can setup a helper method and then attach it to a callback.
```rust, no_run
// our helper
impl Calculator {
fn clear_display(&mut self) {
self.display_value = "0".to_string()
}
}
// our callback
cx.render(rsx!{
button {
onclick: move |_| state.write().clear_display(),
}
})
```

9
docs/guide/src/en/async/index.md
View file

@ -1,9 +0,0 @@
# Working with Async
Often, apps need to interact with file systems, network interfaces, hardware, or timers. This chapter provides an overview of using async code in Dioxus.
## The Runtime
By default, Dioxus-Desktop ships with the `Tokio` runtime and automatically sets everything up for you. This is currently not configurable, though it would be easy to write an integration for Dioxus desktop that uses a different asynchronous runtime.
Dioxus is not currently thread-safe, so any async code you write does *not* need to be `Send/Sync`. That means that you can use non-thread-safe structures like `Cell`, `Rc`, and `RefCell`.

19
docs/guide/src/en/async/spawn.md
View file

@ -1,19 +0,0 @@
# Spawning Futures
The `use_future` and `use_coroutine` hooks are useful if you want to unconditionally spawn the future. Sometimes, though, you'll want to only spawn a future in response to an event, such as a mouse click. For example, suppose you need to send a request when the user clicks a "log in" button. For this, you can use `cx.spawn`:
```rust, no_run
{{#include ../../../examples/spawn.rs:spawn}}
```
> Note: `spawn` will always spawn a _new_ future. You most likely don't want to call it on every render.
Calling `spawn` will give you a `JoinHandle` which lets you cancel or pause the future.
## Spawning Tokio Tasks
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:
```rust, no_run
{{#include ../../../examples/spawn.rs:tokio}}
```

204
docs/guide/src/en/async/use_coroutine.md
View file

@ -1,204 +0,0 @@
# Coroutines
Another tool in your async toolbox are coroutines. Coroutines are futures that can be manually stopped, started, paused, and resumed.
Like regular futures, code in a coroutine will run until the next `await` point before yielding. This low-level control over asynchronous tasks is quite powerful, allowing for infinitely looping tasks like WebSocket polling, background timers, and other periodic actions.
## `use_coroutine`
The `use_coroutine` hook allows you to create a coroutine. Most coroutines we write will be polling loops using async/await.
```rust, no_run
fn app(cx: Scope) -> Element {
let ws: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {
// Connect to some sort of service
let mut conn = connect_to_ws_server().await;
// Wait for data on the service
while let Some(msg) = conn.next().await {
// handle messages
}
});
}
```
For many services, a simple async loop will handle the majority of use cases.
However, if we want to temporarily disable the coroutine, we can "pause" it using the `pause` method, and "resume" it using the `resume` method:
```rust, no_run
let sync: &UseCoroutine<()> = use_coroutine(cx, |rx| async move {
// code for syncing
});
if sync.is_running() {
cx.render(rsx!{
button {
onclick: move |_| sync.pause(),
"Disable syncing"
}
})
} else {
cx.render(rsx!{
button {
onclick: move |_| sync.resume(),
"Enable syncing"
}
})
}
```
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.
## Yielding Values
To yield values from a coroutine, simply bring in a `UseState` handle and set the value whenever your coroutine completes its work.
The future must be `'static` – so any values captured by the task cannot carry any references to `cx`, such as a `UseState`.
You can use [to_owned](https://doc.rust-lang.org/std/borrow/trait.ToOwned.html#tymethod.to_owned) to create a clone of the hook handle which can be moved into the async closure.
```rust, no_run
let sync_status = use_state(cx, || Status::Launching);
let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
let sync_status = sync_status.to_owned();
async move {
loop {
delay_ms(1000).await;
sync_status.set(Status::Working);
}
}
})
```
To make this a bit less verbose, Dioxus exports the `to_owned!` macro which will create a binding as shown above, which can be quite helpful when dealing with many values.
```rust, no_run
let sync_status = use_state(cx, || Status::Launching);
let load_status = use_state(cx, || Status::Launching);
let sync_task = use_coroutine(cx, |rx: UnboundedReceiver<SyncAction>| {
to_owned![sync_status, load_status];
async move {
// ...
}
})
```
## Sending Values
You might've noticed the `use_coroutine` closure takes an argument called `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.
With Coroutines, we can centralize our async logic. The `rx` parameter is an Channel that allows code external to the coroutine to send data _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.
```rust, no_run
use futures_util::stream::StreamExt;
enum ProfileUpdate {
SetUsername(String),
SetAge(i32)
}
let profile = use_coroutine(cx, |mut rx: UnboundedReciver<ProfileUpdate>| async move {
let mut server = connect_to_server().await;
while let Ok(msg) = rx.next().await {
match msg {
ProfileUpdate::SetUsername(name) => server.update_username(name).await,
ProfileUpdate::SetAge(age) => server.update_age(age).await,
}
}
});
cx.render(rsx!{
button {
onclick: move |_| profile.send(ProfileUpdate::SetUsername("Bob".to_string())),
"Update username"
}
})
```
> Note: In order to use/run the `rx.next().await` statement you will need to extend the [`Stream`] trait (used by [`UnboundedReceiver`]) by adding 'futures_util' as a dependency to your project and adding the `use futures_util::stream::StreamExt;`.
For sufficiently complex apps, we could build a bunch of different useful "services" that loop on channels to update the app.
```rust, no_run
let profile = use_coroutine(cx, profile_service);
let editor = use_coroutine(cx, editor_service);
let sync = use_coroutine(cx, sync_service);
async fn profile_service(rx: UnboundedReceiver<ProfileCommand>) {
// do stuff
}
async fn sync_service(rx: UnboundedReceiver<SyncCommand>) {
// do stuff
}
async fn editor_service(rx: UnboundedReceiver<EditorCommand>) {
// do stuff
}
```
We can combine coroutines with [Fermi](https://docs.rs/fermi/latest/fermi/index.html) to emulate Redux Toolkit's Thunk system with much less headache. This lets us store all of our app's state _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 _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.
```rust, no_run
static USERNAME: Atom<String> = Atom(|_| "default".to_string());
fn app(cx: Scope) -> Element {
let atoms = use_atom_root(cx);
use_coroutine(cx, |rx| sync_service(rx, atoms.clone()));
cx.render(rsx!{
Banner {}
})
}
fn Banner(cx: Scope) -> Element {
let username = use_read(cx, &USERNAME);
cx.render(rsx!{
h1 { "Welcome back, {username}" }
})
}
```
Now, in our sync service, we can structure our state however we want. We only need to update the view values when ready.
```rust, no_run
use futures_util::stream::StreamExt;
enum SyncAction {
SetUsername(String),
}
async fn sync_service(mut rx: UnboundedReceiver<SyncAction>, atoms: AtomRoot) {
let username = atoms.write(&USERNAME);
let errors = atoms.write(&ERRORS);
while let Ok(msg) = rx.next().await {
match msg {
SyncAction::SetUsername(name) => {
if set_name_on_server(&name).await.is_ok() {
username.set(name);
} else {
errors.make_mut().push("SetUsernameFailed");
}
}
}
}
}
```
## Automatic injection into the Context API
Coroutine handles are automatically injected through the context API. You can use the `use_coroutine_handle` hook with the message type as a generic to fetch a handle.
```rust, no_run
fn Child(cx: Scope) -> Element {
let sync_task = use_coroutine_handle::<SyncAction>(cx);
sync_task.send(SyncAction::SetUsername);
}
```

41
docs/guide/src/en/async/use_effect.md
View file

@ -1,41 +0,0 @@
# UseEffect
[`use_effect`](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_effect.html) lets you run a callback that returns a future, which will be re-run when its [dependencies](#dependencies) change. This is useful to syncrhonize with external events.
## Dependencies
You can make the callback re-run when some value changes. For example, you might want to fetch a user's data only when the user id changes. You can provide a tuple of "dependencies" to the hook. It will automatically re-run it when any of those dependencies change.
## Example
```rust, no_run
#[inline_props]
fn Profile(cx: Scope, id: usize) -> Element {
let name = use_state(cx, || None);
// Only fetch the user data when the id changes.
use_effect(cx, (id,), |(id,)| {
to_owned![name];
async move {
let user = fetch_user(id).await;
name.set(user.name);
}
});
// Because the dependencies are empty, this will only run once.
// An empty tuple is always equal to an empty tuple.
use_effect(cx, (), |()| async move {
println!("Hello, World!");
});
let name = name.get().clone().unwrap_or("Loading...".to_string());
render!(
p { "{name}" }
)
}
fn app(cx: Scope) -> Element {
render!(Profile { id: 0 })
}
```

31
docs/guide/src/en/async/use_future.md
View file

@ -1,31 +0,0 @@
# UseFuture
[`use_future`](https://docs.rs/dioxus-hooks/latest/dioxus_hooks/fn.use_future.html) lets you run an async closure, and provides you with its result.
For example, we can make an API request (using [reqwest](https://docs.rs/reqwest/latest/reqwest/index.html)) inside `use_future`:
```rust, no_run
{{#include ../../../examples/use_future.rs:use_future}}
```
The code inside `use_future` will be submitted to the Dioxus scheduler once the component has rendered.
We can use `.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 `None`. However, once the future is finished, the component will be re-rendered and the value will now be `Some(...)`, containing the return value of the closure.
We can then render that result:
```rust, no_run
{{#include ../../../examples/use_future.rs:render}}
```
## Restarting the Future
The `UseFuture` handle provides a `restart` method. It can be used to execute the future again, producing a new value.
## Dependencies
Often, you will need to run the future again every time some value (e.g. a prop) changes. Rather than calling `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:
```rust, no_run
{{#include ../../../examples/use_future.rs:dependency}}
```

33
docs/guide/src/en/best_practices/antipatterns.md
View file

@ -1,33 +0,0 @@
# Antipatterns
This example shows what not to do and provides a reason why a given pattern is considered an "AntiPattern". Most anti-patterns are considered wrong for performance or code re-usability reasons.
## Unnecessarily Nested Fragments
Fragments don't mount a physical element to the DOM immediately, so Dioxus must recurse into its children to find a physical DOM node. This process is called "normalization". This means that deeply nested fragments make Dioxus perform unnecessary work. Prefer one or two levels of fragments / nested components until presenting a true DOM element.
Only Component and Fragment nodes are susceptible to this issue. Dioxus mitigates this with components by providing an API for registering shared state without the Context Provider pattern.
```rust, no_run
{{#include ../../../examples/anti_patterns.rs:nested_fragments}}
```
## Incorrect Iterator Keys
As described in the [dynamic rendering chapter](../interactivity/dynamic_rendering.md#the-key-attribute), 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.
```rust, no_run
{{#include ../../../examples/anti_patterns.rs:iter_keys}}
```
## Avoid Interior Mutability in Props
While it is technically acceptable to have a `Mutex` or a `RwLock` in the props, they will be difficult to use.
Suppose you have a struct `User` containing the field `username: String`. If you pass a `Mutex<User>` prop to a `UserComponent` component, that component may wish to pass the username as a `&str` prop to a child component. However, it cannot pass that borrowed field down, since it only would live as long as the `Mutex`'s lock, which belongs to the `UserComponent` function. Therefore, the component will be forced to clone the `username` field.
## Avoid Updating State During Render
Every time you update the state, Dioxus needs to re-render the component – this is inefficient! Consider refactoring your code to avoid this.
Also, if you unconditionally update the state during render, it will be re-rendered in an infinite loop.

153
docs/guide/src/en/best_practices/error_handling.md
View file

@ -1,153 +0,0 @@
# Error handling
A selling point of Rust for web development is the reliability of always knowing where errors can occur and being forced to handle them
However, we haven't talked about error handling at all in this guide! In this chapter, we'll cover some strategies in handling errors to ensure your app never crashes.
## The simplest – returning None
Astute observers might have noticed that `Element` is actually a type alias for `Option<VNode>`. You don't need to know what a `VNode` is, but it's important to recognize that we could actually return nothing at all:
```rust, no_run
fn App(cx: Scope) -> Element {
None
}
```
This lets us add in some syntactic sugar for operations we think _shouldn't_ fail, but we're still not confident enough to "unwrap" on.
> The nature of `Option<VNode>` might change in the future as the `try` trait gets upgraded.
```rust, no_run
fn App(cx: Scope) -> Element {
// immediately return "None"
let name = cx.use_hook(|_| Some("hi"))?;
}
```
## Early return on result
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.
```rust, no_run
fn App(cx: Scope) -> Element {
// Convert Result to Option
let name = cx.use_hook(|_| "1.234").parse().ok()?;
// Early return
let count = cx.use_hook(|_| "1.234");
let val = match count.parse() {
Ok(val) => val
Err(err) => return cx.render(rsx!{ "Parsing failed" })
};
}
```
Notice that while hooks in Dioxus do not like being called in conditionals or loops, they _are_ okay with early returns. Returning an error state early is a completely valid way of handling errors.
## Match results
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.
To do this, we simply have an error state built into our component:
```rust, no_run
let err = use_state(cx, || None);
```
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).
```rust, no_run
fn Commandline(cx: Scope) -> Element {
let error = use_state(cx, || None);
cx.render(match *error {
Some(error) => rsx!(
h1 { "An error occured" }
)
None => rsx!(
input {
oninput: move |_| error.set(Some("bad thing happened!")),
}
)
})
}
```
## Passing error states through components
If you're dealing with a handful of components with minimal nesting, you can just pass the error handle into child components.
```rust, no_run
fn Commandline(cx: Scope) -> Element {
let error = use_state(cx, || None);
if let Some(error) = **error {
return cx.render(rsx!{ "An error occured" });
}
cx.render(rsx!{
Child { error: error.clone() }
Child { error: error.clone() }
Child { error: error.clone() }
Child { error: error.clone() }
})
}
```
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.
## Going global
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.
To get started, consider using a built-in hook like `use_context` and `use_context_provider` or Fermi. Of course, it's pretty easy to roll your own hook too.
At the "top" of our architecture, we're going to want to explicitly declare a value that could be an error.
```rust, no_run
enum InputError {
None,
TooLong,
TooShort,
}
static INPUT_ERROR: Atom<InputError> = Atom(|_| InputError::None);
```
Then, in our top level component, we want to explicitly handle the possible error state for this part of the tree.
```rust, no_run
fn TopLevel(cx: Scope) -> Element {
let error = use_read(cx, &INPUT_ERROR);
match error {
TooLong => return cx.render(rsx!{ "FAILED: Too long!" }),
TooShort => return cx.render(rsx!{ "FAILED: Too Short!" }),
_ => {}
}
}
```
Now, whenever a downstream component has an error in its actions, it can simply just set its own error state:
```rust, no_run
fn Commandline(cx: Scope) -> Element {
let set_error = use_set(cx, &INPUT_ERROR);
cx.render(rsx!{
input {
oninput: move |evt| {
if evt.value.len() > 20 {
set_error(InputError::TooLong);
}
}
}
})
}
```
This approach to error handling is best in apps that have "well defined" error states. Consider using a crate like `thiserror` or `anyhow` to simplify the generation of the error types.
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.

14
docs/guide/src/en/best_practices/index.md
View file

@ -1,14 +0,0 @@
# Best Practices
## Reusable Components
As much as possible, break your code down into small, reusable components and hooks, instead of implementing large chunks of the UI in a single component. This will help you keep the code maintainable – it is much easier to e.g. add, remove or re-order parts of the UI if it is organized in components.
Organize your components in modules to keep the codebase easy to navigate!
## Minimize State Dependencies
While it is possible to share state between components, this should only be done when necessary. Any component that is associated with a particular state object needs to be re-rendered when that state changes. For this reason:
- Keep state local to a component if possible
- When sharing state through props, only pass down the specific data necessary

37
docs/guide/src/en/contributing/guiding_principles.md
View file

@ -1,37 +0,0 @@
# Overall Goals
This document outlines some of the overall goals for Dioxus. These goals are not set in stone, but they represent general guidelines for the project.
The goal of Dioxus is to make it easy to build **cross-platform applications that scale**.
## Cross-Platform
Dioxus is designed to be cross-platform by default. This means that it should be easy to build applications that run on the web, desktop, and mobile. However, Dioxus should also be flexible enough to allow users to opt into platform-specific features when needed. The `use_eval` is one example of this. By default, Dioxus does not assume that the platform supports JavaScript, but it does provide a hook that allows users to opt into JavaScript when needed.
## Performance
As Dioxus applications grow, they should remain relatively performant without the need for manual optimizations. There will be cases where manual optimizations are needed, but Dioxus should try to make these cases as rare as possible.
One of the benefits of the core architecture of Dioxus is that it delivers reasonable performance even when components are rerendered often. It is based on a Virtual Dom which performs diffing which should prevent unnecessary re-renders even when large parts of the component tree are rerun. On top of this, Dioxus groups static parts of the RSX tree together to skip diffing them entirely.
## Type Safety
As teams grow, the Type safety of Rust is a huge advantage. Dioxus should leverage this advantage to make it easy to build applications with large teams.
To take full advantage of Rust's type system, Dioxus should try to avoid exposing public `Any` types and string-ly typed APIs where possible.
## Developer Experience
Dioxus should be easy to learn and ergonomic to use.
- The API of Dioxus attempts to remain close to React's API where possible. This makes it easier for people to learn Dioxus if they already know React
- We can avoid the tradeoff between simplicity and flexibility by providing multiple layers of API: One for the very common use case, one for low-level control
- Hooks: the hooks crate has the most common use cases, but `cx.hook` provides a way to access the underlying persistent reference if needed.
- The builder pattern in platform Configs: The builder pattern is used to default to the most common use case, but users can change the defaults if needed.
- Documentation:
- All public APIs should have rust documentation
- Examples should be provided for all public features. These examples both serve as documentation and testing. They are checked by CI to ensure that they continue to compile
- The most common workflows should be documented in the guide

57
docs/guide/src/en/contributing/index.md
View file

@ -1,57 +0,0 @@
# Contributing
Development happens in the [Dioxus GitHub repository](https://github.com/DioxusLabs/dioxus). If you've found a bug or have an idea for a feature, please submit an issue (but first check if someone hasn't [done it already](https://github.com/DioxusLabs/dioxus/issues)).
[GitHub discussions](https://github.com/DioxusLabs/dioxus/discussions) can be used as a place to ask for help or talk about features. You can also join [our Discord channel](https://discord.gg/XgGxMSkvUM) where some development discussion happens.
## Improving Docs
If you'd like to improve the docs, PRs are welcome! Both Rust docs ([source](https://github.com/DioxusLabs/dioxus/tree/master/packages)) and this guide ([source](https://github.com/DioxusLabs/dioxus/tree/master/docs/guide)) can be found in the GitHub repo.
## Working on the Ecosystem
Part of what makes React great is the rich ecosystem. We'd like the same for Dioxus! So if you have a library in mind that you'd like to write and many people would benefit from, it will be appreciated. You can [browse npm.js](https://www.npmjs.com/search?q=keywords:react-component) for inspiration. Once you are done, add your library to the [awesome dioxus](https://github.com/DioxusLabs/awesome-dioxus) list or share it in the `#I-made-a-thing` channel on [Discord](https://discord.gg/XgGxMSkvUM).
## Bugs & Features
If you've fixed [an open issue](https://github.com/DioxusLabs/dioxus/issues), feel free to submit a PR! You can also take a look at [the roadmap](./roadmap.md) and work on something in there. Consider [reaching out](https://discord.gg/XgGxMSkvUM) to the team first to make sure everyone's on the same page, and you don't do useless work!
All pull requests (including those made by a team member) must be approved by at least one other team member.
Larger, more nuanced decisions about design, architecture, breaking changes, trade-offs, etc. are made by team consensus.
## Tools
The following tools can be helpful when developing Dioxus. Many of these tools are used in the CI pipeline. Running them locally before submitting a PR instead of waiting for CI can save time.
- All code is tested with [cargo test](https://doc.rust-lang.org/cargo/commands/cargo-test.html)
```sh
cargo fmt --all
```
- All code is formatted with [rustfmt](https://github.com/rust-lang/rustfmt)
```sh
cargo check --workspace --examples --tests
```
- All code is linted with [Clippy](https://doc.rust-lang.org/clippy/)
```sh
cargo clippy --workspace --examples --tests -- -D warnings
```
- Browser tests are automated with [Playwright](https://playwright.dev/docs/intro#installing-playwright)
```sh
npx playwright test
```
- Crates that use unsafe are checked for undefined behavior with [MIRI](https://github.com/rust-lang/miri). MIRI can be helpful to debug what unsafe code is causing issues. Only code that does not interact with system calls can be checked with MIRI. Currently, this is used for the two MIRI tests in `dioxus-core` and `dioxus-native-core`.
```sh
cargo miri test --package dioxus-core --test miri_stress
cargo miri test --package dioxus-native-core --test miri_native
```
- [Rust analyzer](https://rust-analyzer.github.io/) can be very helpful for quick feedback in your IDE.

50
docs/guide/src/en/contributing/project_structure.md
View file

@ -1,50 +0,0 @@
# Project Struture
There are many packages in the Dioxus organization. This document will help you understand the purpose of each package and how they fit together.
## Renderers
- [Desktop](https://github.com/DioxusLabs/dioxus/tree/master/packages/desktop): A renderer that runs Dioxus applications natively, but renders them with the system webview.
- [Mobile](https://github.com/DioxusLabs/dioxus/tree/master/packages/mobile): A renderer that runs Dioxus applications natively, but renders them with the system webview. This is currently a copy of the desktop renderer.
- [Web](https://github.com/DioxusLabs/dioxus/tree/master/packages/Web): Renders Dioxus applications in the browser by compiling to WASM and manipulating the DOM.
- [Liveview](https://github.com/DioxusLabs/dioxus/tree/master/packages/liveview): A renderer that runs on the server, and renders using a websocket proxy in the browser.
- [Rink](https://github.com/DioxusLabs/dioxus/tree/master/packages/rink): A renderer that renders a HTML-like tree into a terminal.
- [TUI](https://github.com/DioxusLabs/dioxus/tree/master/packages/dioxus-tui): A renderer that uses Rink to render a Dioxus application in a terminal.
- [Blitz-Core](https://github.com/DioxusLabs/blitz/tree/master/blitz-core): An experimental native renderer that renders a HTML-like tree using WGPU.
- [Blitz](https://github.com/DioxusLabs/blitz): An experimental native renderer that uses Blitz-Core to render a Dioxus application using WGPU.
- [SSR](https://github.com/DioxusLabs/dioxus/tree/master/packages/ssr): A renderer that runs Dioxus applications on the server, and renders them to HTML.
## State Management/Hooks
- [Hooks](https://github.com/DioxusLabs/dioxus/tree/master/packages/hooks): A collection of common hooks for Dioxus applications
- [Signals](https://github.com/DioxusLabs/dioxus/tree/master/packages/signals): A experimental state management library for Dioxus applications. This currently contains a `Copy` version of UseRef
- [Dioxus STD](https://github.com/DioxusLabs/dioxus-std): A collection of platform agnostic hooks to interact with system interfaces (The clipboard, camera, etc.).
- [Fermi](https://github.com/DioxusLabs/dioxus/tree/master/packages/fermi): A global state management library for Dioxus applications.
[Router](https://github.com/DioxusLabs/dioxus/tree/master/packages/router): A client-side router for Dioxus applications
## Core utilities
- [core](https://github.com/DioxusLabs/dioxus/tree/master/packages/core): The core virtual dom implementation every Dioxus application uses
- You can read more about the archetecture of the core [in this blog post](https://dioxuslabs.com/blog/templates-diffing/) and the [custom renderer section of the guide](../custom_renderer/index.md)
- [RSX](https://github.com/DioxusLabs/dioxus/tree/master/packages/RSX): The core parsing for RSX used for hot reloading, autoformatting, and the macro
- [core-macro](https://github.com/DioxusLabs/dioxus/tree/master/packages/core-macro): The rsx! macro used to write Dioxus applications. (This is a wrapper over the RSX crate)
- [HTML macro](https://github.com/DioxusLabs/dioxus-html-macro): A html-like alternative to the RSX macro
## Native Renderer Utilities
- [native-core](https://github.com/DioxusLabs/dioxus/tree/master/packages/native-core): Incrementally computed tree of states (mostly styles)
- You can read more about how native-core can help you build native renderers in the [custom renderer section of the guide](../custom_renderer/index.html#native-core)
- [native-core-macro](https://github.com/DioxusLabs/dioxus/tree/master/packages/native-core-macro): A helper macro for native core
- [Taffy](https://github.com/DioxusLabs/taffy): Layout engine powering Blitz-Core, Rink, and Bevy UI
## Web renderer tooling
- [HTML](https://github.com/DioxusLabs/dioxus/tree/master/packages/html): defines html specific elements, events, and attributes
- [Interpreter](https://github.com/DioxusLabs/dioxus/tree/master/packages/interpreter): defines browser bindings used by the web and desktop renderers
## Developer tooling
- [hot-reload](https://github.com/DioxusLabs/dioxus/tree/master/packages/hot-reload): Macro that uses the RSX crate to hot reload static parts of any rsx! macro. This macro works with any non-web renderer with an [integration](https://crates.io/crates/dioxus-hot-reload)
- [autofmt](https://github.com/DioxusLabs/dioxus/tree/master/packages/autofmt): Formats RSX code
- [rsx-rosetta](https://github.com/DioxusLabs/dioxus/tree/master/packages/RSX-rosetta): Handles conversion between HTML and RSX
- [CLI](https://github.com/DioxusLabs/cli): A Command Line Interface and VSCode extension to assist with Dioxus usage

138
docs/guide/src/en/contributing/roadmap.md
View file

@ -1,138 +0,0 @@
# Roadmap & Feature-set
This feature set and roadmap can help you decide if what Dioxus can do today works for you.
If a feature that you need doesn't exist or you want to contribute to projects on the roadmap, feel free to get involved by [joining the discord](https://discord.gg/XgGxMSkvUM).
Generally, here's the status of each platform:
- **Web**: Dioxus is a great choice for pure web-apps – especially for CRUD/complex apps. However, it does lack the ecosystem of React, so you might be missing a component library or some useful hook.
- **SSR**: Dioxus is a great choice for pre-rendering, hydration, and rendering HTML on a web endpoint. Be warned – the VirtualDom is not (currently) `Send + Sync`.
- **Desktop**: You can build very competent single-window desktop apps right now. However, multi-window apps require support from Dioxus core and are not ready.
- **Mobile**: Mobile support is very young. You'll be figuring things out as you go and there are not many support crates for peripherals.
- **LiveView**: LiveView support is very young. You'll be figuring things out as you go. Thankfully, none of it is too hard and any work can be upstreamed into Dioxus.
## Features
---
| Feature | Status | Description |
| ------------------------- | ------ | -------------------------------------------------------------------- |
| Conditional Rendering | ✅ | if/then to hide/show component |
| Map, Iterator | ✅ | map/filter/reduce to produce rsx! |
| Keyed Components | ✅ | advanced diffing with keys |
| Web | ✅ | renderer for web browser |
| Desktop (webview) | ✅ | renderer for desktop |
| Shared State (Context) | ✅ | share state through the tree |
| Hooks | ✅ | memory cells in components |
| SSR | ✅ | render directly to string |
| Component Children | ✅ | cx.children() as a list of nodes |
| Headless components | ✅ | components that don't return real elements |
| Fragments | ✅ | multiple elements without a real root |
| Manual Props | ✅ | Manually pass in props with spread syntax |
| Controlled Inputs | ✅ | stateful wrappers around inputs |
| CSS/Inline Styles | ✅ | syntax for inline styles/attribute groups |
| Custom elements | ✅ | Define new element primitives |
| Suspense | ✅ | schedule future render from future/promise |
| Integrated error handling | ✅ | Gracefully handle errors with ? syntax |
| NodeRef | ✅ | gain direct access to nodes |
| Re-hydration | ✅ | Pre-render to HTML to speed up first contentful paint |
| Jank-Free Rendering | ✅ | Large diffs are segmented across frames for silky-smooth transitions |
| Effects | ✅ | Run effects after a component has been committed to render |
| Portals | 🛠 | Render nodes outside of the traditional tree structure |
| Cooperative Scheduling | 🛠 | Prioritize important events over non-important events |
| Server Components | 🛠 | Hybrid components for SPA and Server |
| Bundle Splitting | 👀 | Efficiently and asynchronously load the app |
| Lazy Components | 👀 | Dynamically load the new components as the page is loaded |
| 1st class global state | ✅ | redux/recoil/mobx on top of context |
| Runs natively | ✅ | runs as a portable binary w/o a runtime (Node) |
| Subtree Memoization | ✅ | skip diffing static element subtrees |
| High-efficiency templates | ✅ | rsx! calls are translated to templates on the DOM's side |
| Compile-time correct | ✅ | Throw errors on invalid template layouts |
| Heuristic Engine | ✅ | track component memory usage to minimize future allocations |
| Fine-grained reactivity | 👀 | Skip diffing for fine-grain updates |
- ✅ = implemented and working
- 🛠 = actively being worked on
- 👀 = not yet implemented or being worked on
## Roadmap
These Features are planned for the future of Dioxus:
### Core
- [x] Release of Dioxus Core
- [x] Upgrade documentation to include more theory and be more comprehensive
- [x] Support for HTML-side templates for lightning-fast dom manipulation
- [ ] Support for multiple renderers for same virtualdom (subtrees)
- [ ] Support for ThreadSafe (Send + Sync)
- [ ] Support for Portals
### SSR
- [x] SSR Support + Hydration
- [ ] Integrated suspense support for SSR
### Desktop
- [ ] Declarative window management
- [ ] Templates for building/bundling
- [ ] Access to Canvas/WebGL context natively
### Mobile
- [ ] Mobile standard library
- [ ] GPS
- [ ] Camera
- [ ] filesystem
- [ ] Biometrics
- [ ] WiFi
- [ ] Bluetooth
- [ ] Notifications
- [ ] Clipboard
- [ ] Animations
### Bundling (CLI)
- [x] Translation from HTML into RSX
- [x] Dev server
- [x] Live reload
- [x] Translation from JSX into RSX
- [ ] Hot module replacement
- [ ] Code splitting
- [ ] Asset macros
- [ ] Css pipeline
- [ ] Image pipeline
### Essential hooks
- [x] Router
- [x] Global state management
- [ ] Resize observer
## Work in Progress
### Build Tool
We are currently working on our own build tool called [Dioxus CLI](https://github.com/DioxusLabs/cli) which will support:
- an interactive TUI
- on-the-fly reconfiguration
- hot CSS reloading
- two-way data binding between browser and source code
- an interpreter for `rsx!`
- ability to publish to github/netlify/vercel
- bundling for iOS/Desktop/etc
### Server Component Support
While not currently fully implemented, the expectation is that LiveView apps can be a hybrid between Wasm and server-rendered where only portions of a page are "live" and the rest of the page is either server-rendered, statically generated, or handled by the host SPA.
### Native rendering
We are currently working on a native renderer for Dioxus using WGPU called [Blitz](https://github.com/DioxusLabs/blitz/). This will allow you to build apps that are rendered natively for iOS, Android, and Desktop.

136
docs/guide/src/en/contributing/walkthrough_readme.md
View file

@ -1,136 +0,0 @@
# Walkthrough of the Hello World Example Internals
This walkthrough will take you through the internals of the Hello World example program. It will explain how major parts of Dioxus internals interact with each other to take the readme example from a source file to a running application. This guide should serve as a high-level overview of the internals of Dioxus. It is not meant to be a comprehensive guide.
## The Source File
We start will a hello world program. This program renders a desktop app with the text "Hello World" in a webview.
```rust, no_run
{{#include ../../../../../examples/readme.rs}}
```
[![](https://mermaid.ink/img/pako:eNqNkT1vwyAQhv8KvSlR48HphtQtqjK0S6tuSBGBS0CxwcJHk8rxfy_YVqxKVdR3ug_u4YXrQHmNwOFQ-bMyMhB7fReOJbVxfwyyMSy0l7GSpW1ARda727ksUy5MuSyKgvBC5ULA1h5N8WK_kCkfHWHgrBuiXsBynrvdsY9E3u1iM_eyvFOVVadMnELOap-o1911JLPHZ1b-YqLTc3LjTt7WifTZMJPsPdx1ov3Z_ellfcdL8R8vmTy5eUqsTUpZ-vzZzjAEK6gx1NLqtJwuNwSQwRoF8BRqGU4ChOvTORnJf3w7BZxCxBXERkvCjZXpQTXwg6zaVEVtyYe3cdvD0vsf4bucgw?type=png)](https://mermaid.live/edit#pako:eNqNkT1vwyAQhv8KvSlR48HphtQtqjK0S6tuSBGBS0CxwcJHk8rxfy_YVqxKVdR3ug_u4YXrQHmNwOFQ-bMyMhB7fReOJbVxfwyyMSy0l7GSpW1ARda727ksUy5MuSyKgvBC5ULA1h5N8WK_kCkfHWHgrBuiXsBynrvdsY9E3u1iM_eyvFOVVadMnELOap-o1911JLPHZ1b-YqLTc3LjTt7WifTZMJPsPdx1ov3Z_ellfcdL8R8vmTy5eUqsTUpZ-vzZzjAEK6gx1NLqtJwuNwSQwRoF8BRqGU4ChOvTORnJf3w7BZxCxBXERkvCjZXpQTXwg6zaVEVtyYe3cdvD0vsf4bucgw)
## The rsx! Macro
Before the Rust compiler runs the program, it will expand all [macros](https://doc.rust-lang.org/reference/procedural-macros.html). Here is what the hello world example looks like expanded:
```rust, no_run
{{#include ../../../examples/readme_expanded.rs}}
```
The rsx macro separates the static parts of the rsx (the template) and the dynamic parts (the [dynamic_nodes](https://docs.rs/dioxus-core/0.3.2/dioxus_core/prelude/struct.VNode.html#structfield.dynamic_nodes) and [dynamic_attributes](https://docs.rs/dioxus-core/0.3.2/dioxus_core/prelude/struct.VNode.html#structfield.dynamic_attrs)).
The static template only contains the parts of the rsx that cannot change at runtime with holes for the dynamic parts:
[![](https://mermaid.ink/img/pako:eNqdksFuwjAMhl8l8wkkKtFx65njdtm0E0GVSQKJoEmVOgKEeHecUrXStO0wn5Lf9u8vcm6ggjZQwf4UzspiJPH2Ib3g6NLuELG1oiMkp0TsLs9EDu2iUeSCH8tz2HJmy3lRFPrqsXGq9mxeLzcbCU6LZSUGXWRdwnY7tY7Tdoko-Dq1U64fODgiUfzJMeuOe7_ZGq-ny2jNhGQu9DqT8NUK6w72RcL8dxgdzv4PnHLAKf-Fk80HoBUDrfkqeBkTUd8EC2hMbNBpXtYtJySQNQ0PqPioMR4lSH_nOkwUPq9eQUUxmQWkViOZtUN-UwPVHk8dq0Y7CvH9uf3-E9wfrmuk1A?type=png)](https://mermaid.live/edit#pako:eNqdksFuwjAMhl8l8wkkKtFx65njdtm0E0GVSQKJoEmVOgKEeHecUrXStO0wn5Lf9u8vcm6ggjZQwf4UzspiJPH2Ib3g6NLuELG1oiMkp0TsLs9EDu2iUeSCH8tz2HJmy3lRFPrqsXGq9mxeLzcbCU6LZSUGXWRdwnY7tY7Tdoko-Dq1U64fODgiUfzJMeuOe7_ZGq-ny2jNhGQu9DqT8NUK6w72RcL8dxgdzv4PnHLAKf-Fk80HoBUDrfkqeBkTUd8EC2hMbNBpXtYtJySQNQ0PqPioMR4lSH_nOkwUPq9eQUUxmQWkViOZtUN-UwPVHk8dq0Y7CvH9uf3-E9wfrmuk1A)
The dynamic_nodes and dynamic_attributes are the parts of the rsx that can change at runtime:
[![](https://mermaid.ink/img/pako:eNp1UcFOwzAM_RXLVzZpvUbighDiABfgtkxTlnirtSaZUgc0df130hZEEcwny35-79nu0EZHqHDfxA9bmyTw9KIDlGjz7pDMqQZ3DsazhVCQ7dQbwnEiKxwDvN3NqhN4O4C3q_VaIztYKXjkQ7184HcCG3MQSgq6Mes1bjbTPAV3RdqIJN5l-V__2_Fcf5iY68dgG7ZHBT4WD5ftZfIBN7dQ_Tj4w1B9MVTXGZa_GMYdcIGekjfsymW7oaFRavKkUZXUmXTUqENfcCZLfD0Hi0pSpgXmkzNC92zKATyqvWnaUiXHEtPz9KrxY_0nzYOPmA?type=png)](https://mermaid.live/edit#pako:eNp1UcFOwzAM_RXLVzZpvUbighDiABfgtkxTlnirtSaZUgc0df130hZEEcwny35-79nu0EZHqHDfxA9bmyTw9KIDlGjz7pDMqQZ3DsazhVCQ7dQbwnEiKxwDvN3NqhN4O4C3q_VaIztYKXjkQ7184HcCG3MQSgq6Mes1bjbTPAV3RdqIJN5l-V__2_Fcf5iY68dgG7ZHBT4WD5ftZfIBN7dQ_Tj4w1B9MVTXGZa_GMYdcIGekjfsymW7oaFRavKkUZXUmXTUqENfcCZLfD0Hi0pSpgXmkzNC92zKATyqvWnaUiXHEtPz9KrxY_0nzYOPmA)
## Launching the App
The app is launched by calling the `launch` function with the root component. Internally, this function will create a new web view using [wry](https://docs.rs/wry/latest/wry/) and create a virtual dom with the root component (`fn app()` in the readme example). This guide will not explain the renderer in-depth, but you can read more about it in the [custom renderer](/guide/custom-renderer) section.
## The Virtual DOM
Before we dive into the initial render in the virtual DOM, we need to discuss what the virtual DOM is. The virtual DOM is a representation of the DOM that is used to diff the current DOM from the new DOM. This diff is then used to create a list of mutations that need to be applied to the DOM to bring it into sync with the virtual DOM.
The Virtual DOM roughly looks like this:
```rust, no_run
pub struct VirtualDom {
// All the templates that have been created or set during hot reloading
pub(crate) templates: FxHashMap<TemplateId, FxHashMap<usize, Template<'static>>>,
// A slab of all the scopes that have been created
pub(crate) scopes: ScopeSlab,
// All scopes that have been marked as dirty
pub(crate) dirty_scopes: BTreeSet<DirtyScope>,
// Every element is actually a dual reference - one to the template and the other to the dynamic node in that template
pub(crate) elements: Slab<ElementRef>,
// This receiver is used to receive messages from hooks about what scopes need to be marked as dirty
pub(crate) rx: futures_channel::mpsc::UnboundedReceiver<SchedulerMsg>,
// The changes queued up to be sent to the renderer
pub(crate) mutations: Mutations<'static>,
}
```
> What is a [slab](https://docs.rs/slab/latest/slab/)?
>
> A slab acts like a hashmap with integer keys if you don't care about the value of the keys. It is internally backed by a dense vector which makes it more efficient than a hashmap. When you insert a value into a slab, it returns an integer key that you can use to retrieve the value later.
> How does Dioxus use slabs?
>
> Dioxus uses "synchronized slabs" to communicate between the renderer and the VDOM. When a node is created in the Virtual DOM, an (elementId, mutation) pair is passed to the renderer to identify that node, which the renderer will then render in actual DOM. These ids are also used by the Virtual Dom to reference that node in future mutations, like setting an attribute on a node or removing a node. When the renderer sends an event to the Virtual Dom, it sends the ElementId of the node that the event was triggered on. The Virtual DOM uses this id to find that node in the slab and then run the necessary event handlers.
The virtual DOM is a tree of scopes. A new `Scope` is created for every component when it is first rendered and recycled when the component is unmounted.
Scopes serve three main purposes:
1. They store the state of hooks used by the component
2. They store the state for the context API (for example: using
[use_shared_state_provider](https://docs.rs/dioxus/latest/dioxus/prelude/fn.use_shared_state_provider.html)).
3. They store the current and previous versions of the `VNode` that was rendered, so they can be
diffed to generate the set of mutations needed to re-render it.
### The Initial Render
The root scope is created and rebuilt:
1. The root component is run
2. The root component returns a `VNode`
3. Mutations for this `VNode` are created and added to the mutation list (this may involve creating new child components)
4. The `VNode` is stored in the root's `Scope`.
After the root's `Scope` is built, all generated mutations are sent to the renderer, which applies them to the DOM.
After the initial render, the root `Scope` looks like this:
[![](https://mermaid.ink/img/pako:eNqtVE1P4zAQ_SuzPrWikRpWXCLtBRDisItWsOxhCaqM7RKricdyJrQV8N93QtvQNCkfEnOynydv3nxkHoVCbUQipjnOVSYDwc_L1AFbWd3dB-kzuEQkuFLoDUwDFkCZAek9nGDh0RlHK__atA1GkUUHf45f0YbppAqB_aOzIAvz-t7-chN_Y-1bw1WSJKsglIu2w9tktWXxIIuHURT5XCqTYa5NmDguw2R8c5MKq2GcgF46WTB_jafi9rZL0yi5q4jQTSrf9altO4okCn1Ratwyz55Qxuku2ITlTMgs6HCQimsPmb3PvqVi-L5gjXP3QcnxWnL8JZLrwGvR31n0KV-Bx6-r-oVkT_-3G1S-NQLbk9i8rj7udP2cixed2QcDCitHJiQw7ub3EVlNecrPjudG2-6soFO5VbMECmR9T5OnlUY4-AFxfw9aTFst3McU9TK1Otm6NEn_DubBYlX2_dglLXOz48FgwJmJ5lZTlhz6xWgNaFnyDgpymcARHO0W2a9J_l5w2wYXvHuGPcqaQ-rESBQmFNJq3nCPNZoK3l4sUSR81DLMUpG6Z_aTFeHV0imRUKjMSFReSzKnVnKGhUimMi8ZNdoShl-rlfmyOUfCS_cPcePz_B_Wl4pc?type=png)](https://mermaid.live/edit#pako:eNqtVE1P4zAQ_SuzPrWikRpWXCLtBRDisItWsOxhCaqM7RKricdyJrQV8N93QtvQNCkfEnOynydv3nxkHoVCbUQipjnOVSYDwc_L1AFbWd3dB-kzuEQkuFLoDUwDFkCZAek9nGDh0RlHK__atA1GkUUHf45f0YbppAqB_aOzIAvz-t7-chN_Y-1bw1WSJKsglIu2w9tktWXxIIuHURT5XCqTYa5NmDguw2R8c5MKq2GcgF46WTB_jafi9rZL0yi5q4jQTSrf9altO4okCn1Ratwyz55Qxuku2ITlTMgs6HCQimsPmb3PvqVi-L5gjXP3QcnxWnL8JZLrwGvR31n0KV-Bx6-r-oVkT_-3G1S-NQLbk9i8rj7udP2cixed2QcDCitHJiQw7ub3EVlNecrPjudG2-6soFO5VbMECmR9T5OnlUY4-AFxfw9aTFst3McU9TK1Otm6NEn_DubBYlX2_dglLXOz48FgwJmJ5lZTlhz6xWgNaFnyDgpymcARHO0W2a9J_l5w2wYXvHuGPcqaQ-rESBQmFNJq3nCPNZoK3l4sUSR81DLMUpG6Z_aTFeHV0imRUKjMSFReSzKnVnKGhUimMi8ZNdoShl-rlfmyOUfCS_cPcePz_B_Wl4pc)
### Waiting for Events
The Virtual DOM will only ever re-render a `Scope` if it is marked as dirty. Each hook is responsible for marking the `Scope` as dirty if the state has changed. Hooks can mark a scope as dirty by sending a message to the Virtual Dom's channel. You can see the [implementations](https://github.com/DioxusLabs/dioxus/tree/master/packages/hooks) for the hooks dioxus includes by default on how this is done. Calling `needs_update()` on a hook will also cause it to mark its scope as dirty.
There are generally two ways a scope is marked as dirty:
1. The renderer triggers an event: An event listener on this event may be called, which may mark a
component as dirty, if processing the event resulted in any generated any mutations.
2. The renderer calls
[`wait_for_work`](https://docs.rs/dioxus/latest/dioxus/prelude/struct.VirtualDom.html#method.wait_for_work):
This polls dioxus internal future queue. One of these futures may mark a component as dirty.
Once at least one `Scope` is marked as dirty, the renderer can call [`render_with_deadline`](https://docs.rs/dioxus/latest/dioxus/prelude/struct.VirtualDom.html#method.render_with_deadline) to diff the dirty scopes.
### Diffing Scopes
When a user clicks the "up high" button, the root `Scope` will be marked as dirty by the `use_state` hook. The desktop renderer will then call `render_with_deadline`, which will diff the root `Scope`.
To start the diffing process, the component function is run. After the root component is run it, the root `Scope` will look like this:
[![](https://mermaid.ink/img/pako:eNrFVlFP2zAQ_iuen0BrpCaIl0i8AEJ72KQJtpcRFBnbJVYTn-U4tBXw33dpG5M2CetoBfdkny_ffb67fPIT5SAkjekkhxnPmHXk-3WiCVpZ3T9YZjJyDeDIDQcjycRCQVwmCTOGXEBhQEvtVvG1CWUldwo0-XX-6vVIF5W1GB9cWVbI1_PNL5v8jW3uPFbpmFOc2HK-GfA2WG1ZeJSFx0EQmJxxmUEupE01liEd394mVAkyjolYaFYgfu1P6N1dF8Yzua-cA51WphtTWzsLc872Zan9CnEGUkktuk6fFm_i5NxFRwn9bUimHrIvCT3-N2EBM70j5XBNOTwI5TrxmvQJkr7ELcHx67Jeggz0v92g8q0RaE-iP1193On6NyxecKUeJeFQaSdtTMLu_Xah5ctT_u94Nty2ZwU0zxWfxqQA5PecPq84kq9nfRw7SK0WDiEFZ4O37d34S_-08lFBVfb92KVb5HIrAp0WpjKYKeGyODLz0dohWIkaZNkiJqfkdLvIH6oRaTSoEmm0n06k0a5K0ZdpL61Io0Yt0nfpxc7UQ0_9cJrhyZ8syX-6brS706Mc489Vjja7fbWj3cxDqIdfJJqOaCFtwZTAV8hT7U0ovjBQRmiMS8HsNKGJfsE4Vjm4WWhOY2crOaKVEczJS8WwgAWNJywv0SuFcmB_rJ41y9fNiBqm_wA0MS9_AUuAiy0?type=png)](https://mermaid.live/edit#pako:eNrFVlFP2zAQ_iuen0BrpCaIl0i8AEJ72KQJtpcRFBnbJVYTn-U4tBXw33dpG5M2CetoBfdkny_ffb67fPIT5SAkjekkhxnPmHXk-3WiCVpZ3T9YZjJyDeDIDQcjycRCQVwmCTOGXEBhQEvtVvG1CWUldwo0-XX-6vVIF5W1GB9cWVbI1_PNL5v8jW3uPFbpmFOc2HK-GfA2WG1ZeJSFx0EQmJxxmUEupE01liEd394mVAkyjolYaFYgfu1P6N1dF8Yzua-cA51WphtTWzsLc872Zan9CnEGUkktuk6fFm_i5NxFRwn9bUimHrIvCT3-N2EBM70j5XBNOTwI5TrxmvQJkr7ELcHx67Jeggz0v92g8q0RaE-iP1193On6NyxecKUeJeFQaSdtTMLu_Xah5ctT_u94Nty2ZwU0zxWfxqQA5PecPq84kq9nfRw7SK0WDiEFZ4O37d34S_-08lFBVfb92KVb5HIrAp0WpjKYKeGyODLz0dohWIkaZNkiJqfkdLvIH6oRaTSoEmm0n06k0a5K0ZdpL61Io0Yt0nfpxc7UQ0_9cJrhyZ8syX-6brS706Mc489Vjja7fbWj3cxDqIdfJJqOaCFtwZTAV8hT7U0ovjBQRmiMS8HsNKGJfsE4Vjm4WWhOY2crOaKVEczJS8WwgAWNJywv0SuFcmB_rJ41y9fNiBqm_wA0MS9_AUuAiy0)
Next, the Virtual DOM will compare the new VNode with the previous VNode and only update the parts of the tree that have changed. Because of this approach, when a component is re-rendered only the parts of the tree that have changed will be updated in the DOM by the renderer.
The diffing algorithm goes through the list of dynamic attributes and nodes and compares them to the previous VNode. If the attribute or node has changed, a mutation that describes the change is added to the mutation list.
Here is what the diffing algorithm looks like for the root `Scope` (red lines indicate that a mutation was generated, and green lines indicate that no mutation was generated)
[![](https://mermaid.ink/img/pako:eNrFlFFPwjAQx7_KpT7Kko2Elya8qCE-aGLAJ5khpe1Yw9Zbug4k4He3OJjbGPig0T5t17tf_nf777aEo5CEkijBNY-ZsfAwDjW4kxfzhWFZDGNECxOOmYTIYAo2lsCyDG4xzVBLbcv8_RHKSG4V6orSIN0Wxrh8b2RYKr_uTyubd1W92GiWKg7aac6bOU3G803HbVk82xfP_Ok0JEqAT-FeLWJvpFYSOBbaSkMhCMnra5MgtfhWFrPWqHlhL2urT6atbU-oa0PNE8WXFFJ0-nazXakRroddGk9IwYEUnCd5w7Pddr5UTT8ZuVJY5F0fM7ebRLYyXNDgUnprJWxM-9lb7xAQLHe-M2xDYQCD9pD_2hez_kVn-P_rjLq6n3qjYv2iO5qz9DyvPdyv1ETp5eTTJ_7BGvQq8v1TVtl5jXUcRRcrqFh-dI4VtFlBN6t_ynLNkh5JpUmZEm5rbvfhkLiN6H4BQt2jYGYZklC_uzxWWJxsNCfUmkL2SJEJZuWdYs4cKaERS3IXlUJZNI_lGv7cxj2SMf2CeMx5_wBcbK19?type=png)](https://mermaid.live/edit#pako:eNrFlFFPwjAQx7_KpT7Kko2Elya8qCE-aGLAJ5khpe1Yw9Zbug4k4He3OJjbGPig0T5t17tf_nf777aEo5CEkijBNY-ZsfAwDjW4kxfzhWFZDGNECxOOmYTIYAo2lsCyDG4xzVBLbcv8_RHKSG4V6orSIN0Wxrh8b2RYKr_uTyubd1W92GiWKg7aac6bOU3G803HbVk82xfP_Ok0JEqAT-FeLWJvpFYSOBbaSkMhCMnra5MgtfhWFrPWqHlhL2urT6atbU-oa0PNE8WXFFJ0-nazXakRroddGk9IwYEUnCd5w7Pddr5UTT8ZuVJY5F0fM7ebRLYyXNDgUnprJWxM-9lb7xAQLHe-M2xDYQCD9pD_2hez_kVn-P_rjLq6n3qjYv2iO5qz9DyvPdyv1ETp5eTTJ_7BGvQq8v1TVtl5jXUcRRcrqFh-dI4VtFlBN6t_ynLNkh5JpUmZEm5rbvfhkLiN6H4BQt2jYGYZklC_uzxWWJxsNCfUmkL2SJEJZuWdYs4cKaERS3IXlUJZNI_lGv7cxj2SMf2CeMx5_wBcbK19)
## Conclusion
This is only a brief overview of how the Virtual Dom works. There are several aspects not yet covered in this guide including:
* How the Virtual DOM handles async-components
* Keyed diffing
* Using [bump allocation](https://github.com/fitzgen/bumpalo) to efficiently allocate VNodes.
If you need more information about the Virtual Dom, you can read the code of the [core](https://github.com/DioxusLabs/dioxus/tree/master/packages/core) crate or reach out to us on [Discord](https://discord.gg/XgGxMSkvUM).

413
docs/guide/src/en/custom_renderer/index.md
View file

@ -1,413 +0,0 @@
# Custom Renderer
Dioxus is an incredibly portable framework for UI development. The lessons, knowledge, hooks, and components you acquire over time can always be used for future projects. However, sometimes those projects cannot leverage a supported renderer or you need to implement your own better renderer.
Great news: the design of the renderer is entirely up to you! We provide suggestions and inspiration with the 1st party renderers, but only really require processing `Mutations` and sending `UserEvents`.
## The specifics:
Implementing the renderer is fairly straightforward. The renderer needs to:
1. Handle the stream of edits generated by updates to the virtual DOM
2. Register listeners and pass events into the virtual DOM's event system
Essentially, your renderer needs to process edits and generate events to update the VirtualDOM. From there, you'll have everything needed to render the VirtualDOM to the screen.
Internally, Dioxus handles the tree relationship, diffing, memory management, and the event system, leaving as little as possible required for renderers to implement themselves.
For reference, check out the [javascript interpreter](https://github.com/DioxusLabs/dioxus/tree/master/packages/interpreter) or [tui renderer](https://github.com/DioxusLabs/dioxus/tree/master/packages/dioxus-tui) as a starting point for your custom renderer.
## Templates
Dioxus is built around the concept of [Templates](https://docs.rs/dioxus-core/latest/dioxus_core/prelude/struct.Template.html). Templates describe a UI tree known at compile time with dynamic parts filled at runtime. This is useful internally to make skip diffing static nodes, but it is also useful for the renderer to reuse parts of the UI tree. This can be useful for things like a list of items. Each item could contain some static parts and some dynamic parts. The renderer can use the template to create a static part of the UI once, clone it for each element in the list, and then fill in the dynamic parts.
## Mutations
The `Mutation` type is a serialized enum that represents an operation that should be applied to update the UI. The variants roughly follow this set:
```rust, no_run
enum Mutation {
AppendChildren,
AssignId,
CreatePlaceholder,
CreateTextNode,
HydrateText,
LoadTemplate,
ReplaceWith,
ReplacePlaceholder,
InsertAfter,
InsertBefore,
SetAttribute,
SetText,
NewEventListener,
RemoveEventListener,
Remove,
PushRoot,
}
```
The Dioxus diffing mechanism operates as a [stack machine](https://en.wikipedia.org/wiki/Stack_machine) where the [LoadTemplate](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.LoadTemplate), [CreatePlaceholder](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.CreatePlaceholder), and [CreateTextNode](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.CreateTextNode) mutations pushes a new "real" DOM node onto the stack and [AppendChildren](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.AppendChildren), [InsertAfter](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.InsertAfter), [InsertBefore](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.InsertBefore), [ReplacePlaceholder](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.ReplacePlaceholder), and [ReplaceWith](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.ReplaceWith) all remove nodes from the stack.
## Node storage
Dioxus saves and loads elements with IDs. Inside the VirtualDOM, this is just tracked as as a u64.
Whenever a `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 id is used in a mutation. Dioxus reclaims the IDs of elements when removed. To stay in sync with Dioxus you can use a sparse Vec (Vec<Option<T>>) with possibly unoccupied items. You can use the ids as indexes into the Vec for elements, and grow the Vec when an id does not exist.
### An Example
For the sake of understanding, let's consider this example – a very simple UI declaration:
```rust, no_run
rsx!( h1 {"count: {x}"} )
```
#### Building Templates
The above rsx will create a template that contains one static h1 tag and a placeholder for a dynamic text node. The template contains the static parts of the UI, and ids for the dynamic parts along with the paths to access them.
The template will look something like this:
```rust, no_run
Template {
// Some id that is unique for the entire project
name: "main.rs:1:1:0",
// The root nodes of the template
roots: &[
TemplateNode::Element {
tag: "h1",
namespace: None,
attrs: &[],
children: &[
TemplateNode::DynamicText {
id: 0
},
],
}
],
// the path to each of the dynamic nodes
node_paths: &[
// the path to dynamic node with a id of 0
&[
// on the first root node
0,
// the first child of the root node
0,
]
],
// the path to each of the dynamic attributes
attr_paths: &'a [&'a [u8]],
}
```
> For more detailed docs about the struture of templates see the [Template api docs](https://docs.rs/dioxus-core/latest/dioxus_core/prelude/struct.Template.html)
This template will be sent to the renderer in the [list of templates](https://docs.rs/dioxus-core/latest/dioxus_core/struct.Mutations.html#structfield.templates) supplied with the mutations the first time it is used. Any time the renderer encounters a [LoadTemplate](https://docs.rs/dioxus-core/latest/dioxus_core/enum.Mutation.html#variant.LoadTemplate) mutation after this, it should clone the template and store it in the given id.
For dynamic nodes and dynamic text nodes, a placeholder node should be created and inserted into the UI so that the node can be modified later.
In HTML renderers, this template could look like this:
```html
<h1>""</h1>
```
#### Applying Mutations
After the renderer has created all of the new templates, it can begin to process the mutations.
When 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 `<div id="main">` element.
```rust, no_run
instructions: []
stack: [
RootNode,
]
nodes: [
RootNode,
]
```
The 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.
```rust, no_run
instructions: [
LoadTemplate {
// the id of the template
name: "main.rs:1:1:0",
// the index of the root node in the template
index: 0,
// the id to store
id: ElementId(1),
}
]
stack: [
RootNode,
<h1>""</h1>,
]
nodes: [
RootNode,
<h1>""</h1>,
]
```
Next, Dioxus will create the dynamic text node. The diff algorithm decides that this node needs to be created, so Dioxus will generate the Mutation `HydrateText`. When the renderer receives this instruction, it will navigate to the placeholder text node in the template and replace it with the new text.
```rust, no_run
instructions: [
LoadTemplate {
name: "main.rs:1:1:0",
index: 0,
id: ElementId(1),
},
HydrateText {
// the id to store the text node
id: ElementId(2),
// the text to set
text: "count: 0",
}
]
stack: [
RootNode,
<h1>"count: 0"</h1>,
]
nodes: [
RootNode,
<h1>"count: 0"</h1>,
"count: 0",
]
```
Remember, the h1 node is not attached to anything (it is unmounted) so Dioxus needs to generate an Edit that connects the h1 node to the Root. It depends on the situation, but in this case, we use `AppendChildren`. This pops the text node off the stack, leaving the Root element as the next element on the stack.
```rust, no_run
instructions: [
LoadTemplate {
name: "main.rs:1:1:0",
index: 0,
id: ElementId(1),
},
HydrateText {
id: ElementId(2),
text: "count: 0",
},
AppendChildren {
// the id of the parent node
id: ElementId(0),
// the number of nodes to pop off the stack and append
m: 1
}
]
stack: [
RootNode,
]
nodes: [
RootNode,
<h1>"count: 0"</h1>,
"count: 0",
]
```
Over time, our stack looked like this:
```rust, no_run
[Root]
[Root, <h1>""</h1>]
[Root, <h1>"count: 0"</h1>]
[Root]
```
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.
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.
This little demo serves to show exactly how a Renderer would need to process a mutation stream to build UIs.
## Event loop
Like most GUIs, Dioxus relies on an event loop to progress the VirtualDOM. The VirtualDOM itself can produce events as well, so it's important for your custom renderer can handle those too.
The code for the WebSys implementation is straightforward, so we'll add it here to demonstrate how simple an event loop is:
```rust, no_run, ignore
pub async fn run(&mut self) -> dioxus_core::error::Result<()> {
// Push the body element onto the WebsysDom's stack machine
let mut websys_dom = crate::new::WebsysDom::new(prepare_websys_dom());
websys_dom.stack.push(root_node);
// Rebuild or hydrate the virtualdom
let mutations = self.internal_dom.rebuild();
websys_dom.apply_mutations(mutations);
// Wait for updates from the real dom and progress the virtual dom
loop {
let user_input_future = websys_dom.wait_for_event();
let internal_event_future = self.internal_dom.wait_for_work();
match select(user_input_future, internal_event_future).await {
Either::Left((_, _)) => {
let mutations = self.internal_dom.work_with_deadline(|| false);
websys_dom.apply_mutations(mutations);
},
Either::Right((event, _)) => websys_dom.handle_event(event),
}
// render
}
}
```
It's important to decode what the real events are for your event system into Dioxus' synthetic event system (synthetic meaning abstracted). This simply means matching your event type and creating a Dioxus `UserEvent` type. Right now, the virtual event system is modeled almost entirely around the HTML spec, but we are interested in slimming it down.
```rust, no_run, ignore
fn virtual_event_from_websys_event(event: &web_sys::Event) -> VirtualEvent {
match event.type_().as_str() {
"keydown" => {
let event: web_sys::KeyboardEvent = event.clone().dyn_into().unwrap();
UserEvent::KeyboardEvent(UserEvent {
scope_id: None,
priority: EventPriority::Medium,
name: "keydown",
// This should be whatever element is focused
element: Some(ElementId(0)),
data: Arc::new(KeyboardData{
char_code: event.char_code(),
key: event.key(),
key_code: event.key_code(),
alt_key: event.alt_key(),
ctrl_key: event.ctrl_key(),
meta_key: event.meta_key(),
shift_key: event.shift_key(),
location: event.location(),
repeat: event.repeat(),
which: event.which(),
})
})
}
_ => todo!()
}
}
```
## Custom raw elements
If you need to go as far as relying on custom elements/attributes 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. You can drop in your elements any time you want, with little hassle. However, you must be sure your renderer can handle the new namespace.
For more examples and information on how to create custom namespaces, see the [`dioxus_html` crate](https://github.com/DioxusLabs/dioxus/blob/master/packages/html/README.md#how-to-extend-it).
# Native Core
If you are creating a renderer in rust, the [native-core](https://github.com/DioxusLabs/dioxus/tree/master/packages/native-core) crate provides some utilities to implement a renderer. It provides an abstraction over Mutations and Templates and contains helpers that can handle the layout and text editing for you.
## The RealDom
The `RealDom` is a higher-level abstraction over updating the Dom. It uses an entity component system to manage the state of nodes. This system allows you to modify insert and modify arbitrary components on nodes. On top of this, the RealDom provides a way to manage a tree of nodes, and the State trait provides a way to automatically add and update these components when the tree is modified. It also provides a way to apply `Mutations` to the RealDom.
### Example
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:
```rust, no_run
cx.render(rsx!{
div{
color: "red",
p{
border: "1px solid black",
"hello world"
}
}
})
```
In this tree, the color depends on the parent's color. The layout depends on the children's layout, the current text, and the text size. The border depends on only the current node.
In the following diagram arrows represent dataflow:
[![](https://mermaid.ink/img/pako:eNqllV1vgjAUhv8K6W4wkQVa2QdLdrHsdlfukmSptEhjoaSWqTH-9xVwONAKst70g5739JzzlO5BJAgFAYi52EQJlsr6fAszS7d1sVhKnCdWJDJFt6peLVs5-9owohK7HFrVcFJ_pxnpmK8VVvRkTJikkWIiaxy1dhP23bUwW1WW5WbPrrqJ4ziR4EJ6dtVN2ls5y1ZztePUcrWZFCvqVEcPPDffvlyS1XoLIQnVgnVvVPR6FU9Zc-6dV453ojjOPbuetRJ57gIeXQR3cez7rjtteZyZQ2j5MqmjqwE0ZW0VKx9RKtgpFewp1aw3sXXFy6TWgiYlv8mfq1scD8ofbBCAfQg8_AMBOAyBxzEIwA4CxgQ99QbQkjnD2KT7_CfxGF8_9WXQEsq5sDZCcjICOXRCri4h6r3NA38Q6Jdi1EOx5w3DGDYYI6MUvJFjM3VoGHUeGoMd6mBnDmh2E3fo7O4Yhf0x4OkBmIKUyhQzol_GfbkcApXQlIYg0EOC5SoEYXbQ-3ChxHyXRSBQsqBTUOREx_7OsAY3BUGM-VqvUsKUkB_1U6vf05gtweEHTk4_HQ?type=png)](https://mermaid.live/edit#pako:eNqllV1vgjAUhv8K6W4wkQVa2QdLdrHsdlfukmSptEhjoaSWqTH-9xVwONAKst70g5739JzzlO5BJAgFAYi52EQJlsr6fAszS7d1sVhKnCdWJDJFt6peLVs5-9owohK7HFrVcFJ_pxnpmK8VVvRkTJikkWIiaxy1dhP23bUwW1WW5WbPrrqJ4ziR4EJ6dtVN2ls5y1ZztePUcrWZFCvqVEcPPDffvlyS1XoLIQnVgnVvVPR6FU9Zc-6dV453ojjOPbuetRJ57gIeXQR3cez7rjtteZyZQ2j5MqmjqwE0ZW0VKx9RKtgpFewp1aw3sXXFy6TWgiYlv8mfq1scD8ofbBCAfQg8_AMBOAyBxzEIwA4CxgQ99QbQkjnD2KT7_CfxGF8_9WXQEsq5sDZCcjICOXRCri4h6r3NA38Q6Jdi1EOx5w3DGDYYI6MUvJFjM3VoGHUeGoMd6mBnDmh2E3fo7O4Yhf0x4OkBmIKUyhQzol_GfbkcApXQlIYg0EOC5SoEYXbQ-3ChxHyXRSBQsqBTUOREx_7OsAY3BUGM-VqvUsKUkB_1U6vf05gtweEHTk4_HQ)
[//]: # "%% mermaid flow chart"
[//]: # "flowchart TB"
[//]: # " subgraph context"
[//]: # " text_width(text width)"
[//]: # " end"
[//]: # " subgraph state"
[//]: # " direction TB"
[//]: # " subgraph div state"
[//]: # " direction TB"
[//]: # " state1(state)---color1(color)"
[//]: # " linkStyle 0 stroke-width:10px;"
[//]: # " state1---border1(border)"
[//]: # " linkStyle 1 stroke-width:10px;"
[//]: # " text_width-.->layout_width1(layout width)"
[//]: # " linkStyle 2 stroke:#ff5500,stroke-width:4px;"
[//]: # " state1---layout_width1"
[//]: # " linkStyle 3 stroke-width:10px;"
[//]: # " end"
[//]: # " subgraph p state"
[//]: # " direction TB"
[//]: # " state2(state)---color2(color)"
[//]: # " linkStyle 4 stroke-width:10px;"
[//]: # " color1-.->color2"
[//]: # " linkStyle 5 stroke:#0000ff,stroke-width:4px;"
[//]: # " state2---border2(border)"
[//]: # " linkStyle 6 stroke-width:10px;"
[//]: # " text_width-.->layout_width2(layout width)"
[//]: # " linkStyle 7 stroke:#ff5500,stroke-width:4px;"
[//]: # " state2---layout_width2"
[//]: # " linkStyle 8 stroke-width:10px;"
[//]: # " layout_width2-.->layout_width1"
[//]: # " linkStyle 9 stroke:#00aa00,stroke-width:4px;"
[//]: # " end"
[//]: # " subgraph hello world state"
[//]: # " direction TB"
[//]: # " state3(state)---border3(border)"
[//]: # " linkStyle 10 stroke-width:10px;"
[//]: # " state3---color3(color)"
[//]: # " linkStyle 11 stroke-width:10px;"
[//]: # " color2-.->color3"
[//]: # " linkStyle 12 stroke:#0000ff,stroke-width:4px;"
[//]: # " text_width-.->layout_width3(layout width)"
[//]: # " linkStyle 13 stroke:#ff5500,stroke-width:4px;"
[//]: # " state3---layout_width3"
[//]: # " linkStyle 14 stroke-width:10px;"
[//]: # " layout_width3-.->layout_width2"
[//]: # " linkStyle 15 stroke:#00aa00,stroke-width:4px;"
[//]: # " end"
[//]: # " end"
To help in building a Dom, native-core provides the State trait and a RealDom struct. The State trait provides a way to describe how states in a node depend on other states in its relatives. By describing how to update a single node from its relations, native-core will derive a way to update the states of all nodes for you. 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.
Native Core cannot create all of the required methods for the State trait, but it can derive some of them. To implement the State trait, you must implement the following methods and let the `#[partial_derive_state]` macro handle the rest:
```rust, no_run, ignore
{{#include ../../../examples/custom_renderer.rs:derive_state}}
```
Lets take a look at how to implement the State trait for a simple renderer.
```rust, no_run
{{#include ../../../examples/custom_renderer.rs:state_impl}}
```
Now that we have our state, we can put it to use in our RealDom. We can update the RealDom with apply_mutations to update the structure of the dom (adding, removing, and changing properties of nodes) and then update_state to update the States for each of the nodes that changed.
```rust, no_run
{{#include ../../../examples/custom_renderer.rs:rendering}}
```
## Layout
For most platforms, the layout of the Elements will stay the same. The [layout_attributes](https://docs.rs/dioxus-native-core/latest/dioxus_native_core/layout_attributes/index.html) module provides a way to apply HTML attributes a [Taffy](https://docs.rs/taffy/latest/taffy/index.html) layout style.
## Text Editing
To make it easier to implement text editing in rust renderers, `native-core` also contains a renderer-agnostic cursor system. The cursor can handle text editing, selection, and movement with common keyboard shortcuts integrated.
```rust, no_run
{{#include ../../../examples/custom_renderer.rs:cursor}}
```
## Conclusion
That should be it! You should have nearly all the knowledge required on how to implement your 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 [community](https://discord.gg/XgGxMSkvUM).

31
docs/guide/src/en/describing_ui/component_children.md
View file

@ -1,31 +0,0 @@
# Component Children
In some cases, you may wish to create a component that acts as a container for some other content, without the component needing to know what that content is. To achieve this, create a prop of type `Element`:
```rust, no_run
{{#include ../../../examples/component_element_props.rs:Clickable}}
```
Then, when rendering the component, you can pass in the output of `cx.render(rsx!(...))`:
```rust, no_run
{{#include ../../../examples/component_element_props.rs:Clickable_usage}}
```
> Note: Since `Element<'a>` is a borrowed prop, there will be no memoization.
> Warning: While it may compile, do not include the same `Element` more than once in the RSX. The resulting behavior is unspecified.
## The `children` field
Rather than passing the RSX through a regular prop, you may wish to accept children similarly to how elements can have children. The "magic" `children` prop lets you achieve this:
```rust, no_run
{{#include ../../../examples/component_children.rs:Clickable}}
```
This makes using the component much simpler: simply put the RSX inside the `{}` brackets – and there is no need for a `render` call or another macro!
```rust, no_run
{{#include ../../../examples/component_children.rs:Clickable_usage}}
```

144
docs/guide/src/en/describing_ui/component_props.md
View file

@ -1,144 +0,0 @@
# Component Props
Just like you can pass arguments to a function, you can pass props to a component that customize its behavior! The components we've seen so far didn't accept any props – so let's write some components that do.
## `#[derive(Props)]`
Component props are a single struct annotated with `#[derive(Props)]`. For a component to accept props, the type of its argument must be `Scope<YourPropsStruct>`. Then, you can access the value of the props using `cx.props`.
There are 2 flavors of Props structs:
- Owned props:
- Don't have an associated lifetime
- Implement `PartialEq`, allow for memoization (if the props don't change, Dioxus won't re-render the component)
- Borrowed props:
- [Borrow](https://doc.rust-lang.org/beta/rust-by-example/scope/borrow.html) from a parent component
- Cannot be memoized due to lifetime constraints
### Owned Props
Owned Props are very simple – they don't borrow anything. Example:
```rust, no_run
{{#include ../../../examples/component_owned_props.rs:Likes}}
```
You can then pass prop values to the component the same way you would pass attributes to an element:
```rust, no_run
{{#include ../../../examples/component_owned_props.rs:App}}
```
![Screenshot: Likes component](./images/component_owned_props_screenshot.png)
### Borrowed Props
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 `App` Component to a `TitleCard` subcomponent? A naive solution might be to [`.clone()`](https://doc.rust-lang.org/std/clone/trait.Clone.html) the String, creating a copy of it for the subcomponent – but this would be inefficient, especially for larger Strings.
Rust allows for something more efficient – borrowing the String as a `&str` – this is what Borrowed Props are for!
```rust, no_run
{{#include ../../../examples/component_borrowed_props.rs:TitleCard}}
```
We can then use the component like this:
```rust, no_run
{{#include ../../../examples/component_borrowed_props.rs:App}}
```
![Screenshot: TitleCard component](./images/component_borrowed_props_screenshot.png)
Borrowed props can be very useful, but they do not allow for memorization so they will _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.
## Prop Options
The `#[derive(Props)]` macro has some features that let you customize the behavior of props.
### Optional Props
You can create optional fields by using the `Option<…>` type for a field:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:OptionalProps}}
```
Then, you can choose to either provide them or not:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:OptionalProps_usage}}
```
### Explicitly Required `Option`s
If you want to explicitly require an `Option`, and not an optional prop, you can annotate it with `#[props(!optional)]`:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:ExplicitOption}}
```
Then, you have to explicitly pass either `Some("str")` or `None`:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:ExplicitOption_usage}}
```
### Default Props
You can use `#[props(default = 42)]` to make a field optional and specify its default value:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:DefaultComponent}}
```
Then, similarly to optional props, you don't have to provide it:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:DefaultComponent_usage}}
```
### Automatic Conversion with `.into`
It is common for Rust functions to accept `impl Into<SomeType>` rather than just `SomeType` to support a wider range of parameters. If you want similar functionality with props, you can use `#[props(into)]`. For example, you could add it on a `String` prop – and `&str` will also be automatically accepted, as it can be converted into `String`:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:IntoComponent}}
```
Then, you can use it so:
```rust, no_run
{{#include ../../../examples/component_props_options.rs:IntoComponent_usage}}
```
## The `inline_props` macro
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 `cx.props.whatever`, we could just use `whatever` directly!
`inline_props` allows you to do just that. Instead of typing the "full" version:
```rust, no_run
#[derive(Props, PartialEq)]
struct TitleCardProps {
title: String,
}
fn TitleCard(cx: Scope<TitleCardProps>) -> Element {
cx.render(rsx!{
h1 { "{cx.props.title}" }
})
}
```
...you can define a function that accepts props as arguments. Then, just annotate it with `#[inline_props]`, and the macro will turn it into a regular Component for you:
```rust, no_run
#[inline_props]
fn TitleCard(cx: Scope, title: String) -> Element {
cx.render(rsx!{
h1 { "{title}" }
})
}
```
> 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.

27
docs/guide/src/en/describing_ui/components.md
View file

@ -1,27 +0,0 @@
# Components
Just like you wouldn't want to write a complex program in a single, long, `main` function, you shouldn't build a complex UI in a single `App` function. Instead, you should break down the functionality of an app in logical parts called components.
A component is a Rust function, named in UpperCammelCase, that takes a `Scope` parameter and returns an `Element` describing the UI it wants to render. In fact, our `App` function is a component!
```rust, no_run
{{#include ../../../examples/hello_world_desktop.rs:component}}
```
> You'll probably want to add `#![allow(non_snake_case)]` to the top of your crate to avoid warnings about UpperCammelCase component names
A Component is responsible for some rendering task – typically, rendering an isolated part of the user interface. For example, you could have an `About` component that renders a short description of Dioxus Labs:
```rust, no_run
{{#include ../../../examples/components.rs:About}}
```
Then, you can render your component in another component, similarly to how elements are rendered:
```rust, no_run
{{#include ../../../examples/components.rs:App}}
```
![Screenshot containing the About component twice](./images/screenshot_about_component.png)
> 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!

BIN
docs/guide/src/en/describing_ui/images/component_borrowed_props_screenshot.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 7.7 KiB

Some files were not shown because too many files have changed in this diff Show more