Document not found (404)
-This URL is invalid, sorry. Please use the navigation bar or search to continue.
- -"),i.setHtml(f),i.show(),t._signal("showGutterTooltip",i),t.on("mousewheel",c);if(e.$tooltipFollowsMouse)h(u);else{var p=u.domEvent.target,d=p.getBoundingClientRect(),v=i.getElement().style;v.left=d.right+"px",v.top=d.bottom+"px"}}function c(){o&&(o=clearTimeout(o)),f&&(i.hide(),f=null,t._signal("hideGutterTooltip",i),t.removeEventListener("mousewheel",c))}function h(e){i.setPosition(e.x,e.y)}var t=e.editor,n=t.renderer.$gutterLayer,i=new a(t.container);e.editor.setDefaultHandler("guttermousedown",function(r){if(!t.isFocused()||r.getButton()!=0)return;var i=n.getRegion(r);if(i=="foldWidgets")return;var s=r.getDocumentPosition().row,o=t.session.selection;if(r.getShiftKey())o.selectTo(s,0);else{if(r.domEvent.detail==2)return t.selectAll(),r.preventDefault();e.$clickSelection=t.selection.getLineRange(s)}return e.setState("selectByLines"),e.captureMouse(r),r.preventDefault()});var o,u,f;e.editor.setDefaultHandler("guttermousemove",function(t){var n=t.domEvent.target||t.domEvent.srcElement;if(r.hasCssClass(n,"ace_fold-widget"))return c();f&&e.$tooltipFollowsMouse&&h(t),u=t;if(o)return;o=setTimeout(function(){o=null,u&&!e.isMousePressed?l():c()},50)}),s.addListener(t.renderer.$gutter,"mouseout",function(e){u=null;if(!f||o)return;o=setTimeout(function(){o=null,c()},50)}),t.on("changeSession",c)}function a(e){o.call(this,e)}var r=e("../lib/dom"),i=e("../lib/oop"),s=e("../lib/event"),o=e("../tooltip").Tooltip;i.inherits(a,o),function(){this.setPosition=function(e,t){var n=window.innerWidth||document.documentElement.clientWidth,r=window.innerHeight||document.documentElement.clientHeight,i=this.getWidth(),s=this.getHeight();e+=15,t+=15,e+i>n&&(e-=e+i-n),t+s>r&&(t-=20+s),o.prototype.setPosition.call(this,e,t)}}.call(a.prototype),t.GutterHandler=u}),ace.define("ace/mouse/mouse_event",["require","exports","module","ace/lib/event","ace/lib/useragent"],function(e,t,n){"use strict";var r=e("../lib/event"),i=e("../lib/useragent"),s=t.MouseEvent=function(e,t){this.domEvent=e,this.editor=t,this.x=this.clientX=e.clientX,this.y=this.clientY=e.clientY,this.$pos=null,this.$inSelection=null,this.propagationStopped=!1,this.defaultPrevented=!1};(function(){this.stopPropagation=function(){r.stopPropagation(this.domEvent),this.propagationStopped=!0},this.preventDefault=function(){r.preventDefault(this.domEvent),this.defaultPrevented=!0},this.stop=function(){this.stopPropagation(),this.preventDefault()},this.getDocumentPosition=function(){return this.$pos?this.$pos:(this.$pos=this.editor.renderer.screenToTextCoordinates(this.clientX,this.clientY),this.$pos)},this.inSelection=function(){if(this.$inSelection!==null)return this.$inSelection;var e=this.editor,t=e.getSelectionRange();if(t.isEmpty())this.$inSelection=!1;else{var n=this.getDocumentPosition();this.$inSelection=t.contains(n.row,n.column)}return this.$inSelection},this.getButton=function(){return r.getButton(this.domEvent)},this.getShiftKey=function(){return this.domEvent.shiftKey},this.getAccelKey=i.isMac?function(){return this.domEvent.metaKey}:function(){return this.domEvent.ctrlKey}}).call(s.prototype)}),ace.define("ace/mouse/dragdrop_handler",["require","exports","module","ace/lib/dom","ace/lib/event","ace/lib/useragent"],function(e,t,n){"use strict";function f(e){function T(e,n){var r=Date.now(),i=!n||e.row!=n.row,s=!n||e.column!=n.column;if(!S||i||s)t.moveCursorToPosition(e),S=r,x={x:p,y:d};else{var o=l(x.x,x.y,p,d);o>a?S=null:r-S>=u&&(t.renderer.scrollCursorIntoView(),S=null)}}function N(e,n){var r=Date.now(),i=t.renderer.layerConfig.lineHeight,s=t.renderer.layerConfig.characterWidth,u=t.renderer.scroller.getBoundingClientRect(),a={x:{left:p-u.left,right:u.right-p},y:{top:d-u.top,bottom:u.bottom-d}},f=Math.min(a.x.left,a.x.right),l=Math.min(a.y.top,a.y.bottom),c={row:e.row,column:e.column};f/s<=2&&(c.column+=a.x.left
"),p.appendChild(i.createElement("div"));var m=function(e,t,n){if(t===0&&(n==="esc"||n==="return"))return h.destroy(),{command:"null"}};h.destroy=function(){if(e.$mouseHandler.isMousePressed)return;e.keyBinding.removeKeyboardHandler(m),n.widgetManager.removeLineWidget(h),e.off("changeSelection",h.destroy),e.off("changeSession",h.destroy),e.off("mouseup",h.destroy),e.off("change",h.destroy)},e.keyBinding.addKeyboardHandler(m),e.on("changeSelection",h.destroy),e.on("changeSession",h.destroy),e.on("mouseup",h.destroy),e.on("change",h.destroy),e.session.widgetManager.addLineWidget(h),h.el.onmousedown=e.focus.bind(e),e.renderer.scrollCursorIntoView(null,.5,{bottom:h.el.offsetHeight})},i.importCssString(" .error_widget_wrapper { background: inherit; color: inherit; border:none } .error_widget { border-top: solid 2px; border-bottom: solid 2px; margin: 5px 0; padding: 10px 40px; white-space: pre-wrap; } .error_widget.ace_error, .error_widget_arrow.ace_error{ border-color: #ff5a5a } .error_widget.ace_warning, .error_widget_arrow.ace_warning{ border-color: #F1D817 } .error_widget.ace_info, .error_widget_arrow.ace_info{ border-color: #5a5a5a } .error_widget.ace_ok, .error_widget_arrow.ace_ok{ border-color: #5aaa5a } .error_widget_arrow { position: absolute; border: solid 5px; border-top-color: transparent!important; border-right-color: transparent!important; border-left-color: transparent!important; top: -5px; }","")}),ace.define("ace/ace",["require","exports","module","ace/lib/fixoldbrowsers","ace/lib/dom","ace/lib/event","ace/range","ace/editor","ace/edit_session","ace/undomanager","ace/virtual_renderer","ace/worker/worker_client","ace/keyboard/hash_handler","ace/placeholder","ace/multi_select","ace/mode/folding/fold_mode","ace/theme/textmate","ace/ext/error_marker","ace/config"],function(e,t,n){"use strict";e("./lib/fixoldbrowsers");var r=e("./lib/dom"),i=e("./lib/event"),s=e("./range").Range,o=e("./editor").Editor,u=e("./edit_session").EditSession,a=e("./undomanager").UndoManager,f=e("./virtual_renderer").VirtualRenderer;e("./worker/worker_client"),e("./keyboard/hash_handler"),e("./placeholder"),e("./multi_select"),e("./mode/folding/fold_mode"),e("./theme/textmate"),e("./ext/error_marker"),t.config=e("./config"),t.require=e,typeof define=="function"&&(t.define=define),t.edit=function(e,n){if(typeof e=="string"){var s=e;e=document.getElementById(s);if(!e)throw new Error("ace.edit can't find div #"+s)}if(e&&e.env&&e.env.editor instanceof o)return e.env.editor;var u="";if(e&&/input|textarea/i.test(e.tagName)){var a=e;u=a.value,e=r.createElement("pre"),a.parentNode.replaceChild(e,a)}else e&&(u=e.textContent,e.innerHTML="");var l=t.createEditSession(u),c=new o(new f(e),l,n),h={document:l,editor:c,onResize:c.resize.bind(c,null)};return a&&(h.textarea=a),i.addListener(window,"resize",h.onResize),c.on("destroy",function(){i.removeListener(window,"resize",h.onResize),h.editor.container.env=null}),c.container.env=c.env=h,c},t.createEditSession=function(e,t){var n=new u(e,t);return n.setUndoManager(new a),n},t.Range=s,t.Editor=o,t.EditSession=u,t.UndoManager=a,t.VirtualRenderer=f,t.version="1.4.4"}); (function() { - ace.require(["ace/ace"], function(a) { - if (a) { - a.config.init(true); - a.define = ace.define; - } - if (!window.ace) - window.ace = a; - for (var key in a) if (a.hasOwnProperty(key)) - window.ace[key] = a[key]; - window.ace["default"] = window.ace; - if (typeof module == "object" && typeof exports == "object" && module) { - module.exports = window.ace; - } - }); - })(); diff --git a/docs/nightly/guide/en/async/index.html b/docs/nightly/guide/en/async/index.html deleted file mode 100644 index f5987a40f..000000000 --- a/docs/nightly/guide/en/async/index.html +++ /dev/null @@ -1,223 +0,0 @@ - - - - - -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/async/spawn.html b/docs/nightly/guide/en/async/spawn.html
deleted file mode 100644
index 0ce2ea479..000000000
--- a/docs/nightly/guide/en/async/spawn.html
+++ /dev/null
@@ -1,277 +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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/async/use_coroutine.html b/docs/nightly/guide/en/async/use_coroutine.html
deleted file mode 100644
index e9363c5d0..000000000
--- a/docs/nightly/guide/en/async/use_coroutine.html
+++ /dev/null
@@ -1,421 +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:
--#![allow(unused)] -fn main() { - 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", - } - }) -} -
--Note:
-spawnwill 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:
-- --#![allow(unused)] -fn main() { - cx.spawn(async { - let _ = tokio::spawn(async {}).await; - - let _ = tokio::task::spawn_local(async { - // some !Send work - }) - .await; - }); -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/async/use_future.html b/docs/nightly/guide/en/async/use_future.html
deleted file mode 100644
index 3acbb115f..000000000
--- a/docs/nightly/guide/en/async/use_future.html
+++ /dev/null
@@ -1,274 +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.
--#![allow(unused)] -fn main() { -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:
--#![allow(unused)] -fn main() { -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 to create a clone of the hook handle which can be moved into the async closure.
---#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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().awaitstatement you will need to extend the [Stream] trait (used by [UnboundedReceiver]) by adding 'futures_util' as a dependency to your project and adding theuse 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.
---#![allow(unused)] -fn main() { -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 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.
---#![allow(unused)] -fn main() { -static USERNAME: Atom<String> = |_| "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.
---#![allow(unused)] -fn main() { -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.
- --#![allow(unused)] -fn main() { -fn Child(cx: Scope) -> Element { - let sync_task = use_coroutine_handle::<SyncAction>(cx); - - sync_task.send(SyncAction::SetUsername); -} -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/ayu-highlight.css b/docs/nightly/guide/en/ayu-highlight.css
deleted file mode 100644
index 0c45c6f14..000000000
--- a/docs/nightly/guide/en/ayu-highlight.css
+++ /dev/null
@@ -1,79 +0,0 @@
-/*
-Based off of the Ayu theme
-Original by Dempfi (https://github.com/dempfi/ayu)
-*/
-
-.hljs {
- display: block;
- overflow-x: auto;
- background: #191f26;
- color: #e6e1cf;
- padding: 0.5em;
-}
-
-.hljs-comment,
-.hljs-quote {
- color: #5c6773;
- font-style: italic;
-}
-
-.hljs-variable,
-.hljs-template-variable,
-.hljs-attribute,
-.hljs-attr,
-.hljs-regexp,
-.hljs-link,
-.hljs-selector-id,
-.hljs-selector-class {
- color: #ff7733;
-}
-
-.hljs-number,
-.hljs-meta,
-.hljs-builtin-name,
-.hljs-literal,
-.hljs-type,
-.hljs-params {
- color: #ffee99;
-}
-
-.hljs-string,
-.hljs-bullet {
- color: #b8cc52;
-}
-
-.hljs-title,
-.hljs-built_in,
-.hljs-section {
- color: #ffb454;
-}
-
-.hljs-keyword,
-.hljs-selector-tag,
-.hljs-symbol {
- color: #ff7733;
-}
-
-.hljs-name {
- color: #36a3d9;
-}
-
-.hljs-tag {
- color: #00568d;
-}
-
-.hljs-emphasis {
- font-style: italic;
-}
-
-.hljs-strong {
- font-weight: bold;
-}
-
-.hljs-addition {
- color: #91b362;
-}
-
-.hljs-deletion {
- color: #d96c75;
-}
diff --git a/docs/nightly/guide/en/best_practices/antipatterns.html b/docs/nightly/guide/en/best_practices/antipatterns.html
deleted file mode 100644
index 509d123fd..000000000
--- a/docs/nightly/guide/en/best_practices/antipatterns.html
+++ /dev/null
@@ -1,288 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- UseFuture
-use_future lets you run an async closure, and provides you with its result.
For example, we can make an API request (using reqwest) inside use_future:
--#![allow(unused)] -fn main() { -let future = use_future(cx, (), |_| async move { - reqwest::get("https://dog.ceo/api/breeds/image/random") - .await - .unwrap() - .json::<ApiResponse>() - .await -}); -} -
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:
---#![allow(unused)] -fn main() { -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..." } }, -}) -} -
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:
- --#![allow(unused)] -fn main() { -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 -}); -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/best_practices/error_handling.html b/docs/nightly/guide/en/best_practices/error_handling.html
deleted file mode 100644
index 96a26b2cb..000000000
--- a/docs/nightly/guide/en/best_practices/error_handling.html
+++ /dev/null
@@ -1,367 +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.
---#![allow(unused)] -fn main() { - // ❌ 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!" } - )) -} -
Incorrect Iterator Keys
-As described in the dynamic rendering chapter, list items must have unique keys that are associated with the same items across renders. This helps Dioxus associate state with the contained components and ensures good diffing performance. Do not omit keys, unless you know that the list will never change.
---#![allow(unused)] -fn main() { - 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}" } - )) - } - }) -} -
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.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/best_practices/index.html b/docs/nightly/guide/en/best_practices/index.html
deleted file mode 100644
index 007cdc283..000000000
--- a/docs/nightly/guide/en/best_practices/index.html
+++ /dev/null
@@ -1,228 +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:
--#![allow(unused)] -fn main() { -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 thetrytrait gets upgraded.
--#![allow(unused)] -fn main() { -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.
---#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -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).
---#![allow(unused)] -fn main() { -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.
---#![allow(unused)] -fn main() { -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.
---#![allow(unused)] -fn main() { -enum InputError { - None, - TooLong, - TooShort, -} - -static INPUT_ERROR: Atom<InputError> = |_| InputError::None; -} -
Then, in our top level component, we want to explicitly handle the possible error state for this part of the tree.
---#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -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.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/book.js b/docs/nightly/guide/en/book.js
deleted file mode 100644
index aa153a3e1..000000000
--- a/docs/nightly/guide/en/book.js
+++ /dev/null
@@ -1,762 +0,0 @@
-"use strict";
-
-// Fix back button cache problem
-window.onunload = function () { };
-
-// Global variable, shared between modules
-function playground_text(playground) {
- let code_block = playground.querySelector("code");
-
- if (window.ace && code_block.classList.contains("editable")) {
- let editor = window.ace.edit(code_block);
- return editor.getValue();
- } else {
- return code_block.textContent;
- }
-}
-
-(function codeSnippets() {
- function fetch_with_timeout(url, options, timeout = 6000) {
- return Promise.race([
- fetch(url, options),
- new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout))
- ]);
- }
-
- var playgrounds = Array.from(document.querySelectorAll(".playground"));
- if (playgrounds.length > 0) {
- fetch_with_timeout("https://play.rust-lang.org/meta/crates", {
- headers: {
- 'Content-Type': "application/json",
- },
- method: 'POST',
- mode: 'cors',
- })
- .then(response => response.json())
- .then(response => {
- // get list of crates available in the rust playground
- let playground_crates = response.crates.map(item => item["id"]);
- playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
- });
- }
-
- function handle_crate_list_update(playground_block, playground_crates) {
- // update the play buttons after receiving the response
- update_play_button(playground_block, playground_crates);
-
- // and install on change listener to dynamically update ACE editors
- if (window.ace) {
- let code_block = playground_block.querySelector("code");
- if (code_block.classList.contains("editable")) {
- let editor = window.ace.edit(code_block);
- editor.addEventListener("change", function (e) {
- update_play_button(playground_block, playground_crates);
- });
- // add Ctrl-Enter command to execute rust code
- editor.commands.addCommand({
- name: "run",
- bindKey: {
- win: "Ctrl-Enter",
- mac: "Ctrl-Enter"
- },
- exec: _editor => run_rust_code(playground_block)
- });
- }
- }
- }
-
- // updates the visibility of play button based on `no_run` class and
- // used crates vs ones available on http://play.rust-lang.org
- function update_play_button(pre_block, playground_crates) {
- var play_button = pre_block.querySelector(".play-button");
-
- // skip if code is `no_run`
- if (pre_block.querySelector('code').classList.contains("no_run")) {
- play_button.classList.add("hidden");
- return;
- }
-
- // get list of `extern crate`'s from snippet
- var txt = playground_text(pre_block);
- var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
- var snippet_crates = [];
- var item;
- while (item = re.exec(txt)) {
- snippet_crates.push(item[1]);
- }
-
- // check if all used crates are available on play.rust-lang.org
- var all_available = snippet_crates.every(function (elem) {
- return playground_crates.indexOf(elem) > -1;
- });
-
- if (all_available) {
- play_button.classList.remove("hidden");
- } else {
- play_button.classList.add("hidden");
- }
- }
-
- function run_rust_code(code_block) {
- var result_block = code_block.querySelector(".result");
- if (!result_block) {
- result_block = document.createElement('code');
- result_block.className = 'result hljs language-bash';
-
- code_block.append(result_block);
- }
-
- let text = playground_text(code_block);
- let classes = code_block.querySelector('code').classList;
- let edition = "2015";
- if(classes.contains("edition2018")) {
- edition = "2018";
- } else if(classes.contains("edition2021")) {
- edition = "2021";
- }
- var params = {
- version: "stable",
- optimize: "0",
- code: text,
- edition: edition
- };
-
- if (text.indexOf("#![feature") !== -1) {
- params.version = "nightly";
- }
-
- result_block.innerText = "Running...";
-
- fetch_with_timeout("https://play.rust-lang.org/evaluate.json", {
- headers: {
- 'Content-Type': "application/json",
- },
- method: 'POST',
- mode: 'cors',
- body: JSON.stringify(params)
- })
- .then(response => response.json())
- .then(response => {
- if (response.result.trim() === '') {
- result_block.innerText = "No output";
- result_block.classList.add("result-no-output");
- } else {
- result_block.innerText = response.result;
- result_block.classList.remove("result-no-output");
- }
- })
- .catch(error => result_block.innerText = "Playground Communication: " + error.message);
- }
-
- // Syntax highlighting Configuration
- hljs.configure({
- tabReplace: ' ', // 4 spaces
- languages: [], // Languages used for auto-detection
- });
-
- let code_nodes = Array
- .from(document.querySelectorAll('code'))
- // Don't highlight `inline code` blocks in headers.
- .filter(function (node) {return !node.parentElement.classList.contains("header"); });
-
- if (window.ace) {
- // language-rust class needs to be removed for editable
- // blocks or highlightjs will capture events
- code_nodes
- .filter(function (node) {return node.classList.contains("editable"); })
- .forEach(function (block) { block.classList.remove('language-rust'); });
-
- Array
- code_nodes
- .filter(function (node) {return !node.classList.contains("editable"); })
- .forEach(function (block) { hljs.highlightBlock(block); });
- } else {
- code_nodes.forEach(function (block) { hljs.highlightBlock(block); });
- }
-
- // Adding the hljs class gives code blocks the color css
- // even if highlighting doesn't apply
- code_nodes.forEach(function (block) { block.classList.add('hljs'); });
-
- Array.from(document.querySelectorAll("code.language-rust")).forEach(function (block) {
-
- var lines = Array.from(block.querySelectorAll('.boring'));
- // If no lines were hidden, return
- if (!lines.length) { return; }
- block.classList.add("hide-boring");
-
- var buttons = document.createElement('div');
- buttons.className = 'buttons';
- buttons.innerHTML = "";
-
- // add expand button
- var pre_block = block.parentNode;
- pre_block.insertBefore(buttons, pre_block.firstChild);
-
- pre_block.querySelector('.buttons').addEventListener('click', function (e) {
- if (e.target.classList.contains('fa-eye')) {
- e.target.classList.remove('fa-eye');
- e.target.classList.add('fa-eye-slash');
- e.target.title = 'Hide lines';
- e.target.setAttribute('aria-label', e.target.title);
-
- block.classList.remove('hide-boring');
- } else if (e.target.classList.contains('fa-eye-slash')) {
- e.target.classList.remove('fa-eye-slash');
- e.target.classList.add('fa-eye');
- e.target.title = 'Show hidden lines';
- e.target.setAttribute('aria-label', e.target.title);
-
- block.classList.add('hide-boring');
- }
- });
- });
-
- if (window.playground_copyable) {
- Array.from(document.querySelectorAll('pre code')).forEach(function (block) {
- var pre_block = block.parentNode;
- if (!pre_block.classList.contains('playground')) {
- var buttons = pre_block.querySelector(".buttons");
- if (!buttons) {
- buttons = document.createElement('div');
- buttons.className = 'buttons';
- pre_block.insertBefore(buttons, pre_block.firstChild);
- }
-
- var clipButton = document.createElement('button');
- clipButton.className = 'fa fa-copy clip-button';
- clipButton.title = 'Copy to clipboard';
- clipButton.setAttribute('aria-label', clipButton.title);
- clipButton.innerHTML = '';
-
- buttons.insertBefore(clipButton, buttons.firstChild);
- }
- });
- }
-
- // Process playground code blocks
- Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) {
- // Add play button
- var buttons = pre_block.querySelector(".buttons");
- if (!buttons) {
- buttons = document.createElement('div');
- buttons.className = 'buttons';
- pre_block.insertBefore(buttons, pre_block.firstChild);
- }
-
- var runCodeButton = document.createElement('button');
- runCodeButton.className = 'fa fa-play play-button';
- runCodeButton.hidden = true;
- runCodeButton.title = 'Run this code';
- runCodeButton.setAttribute('aria-label', runCodeButton.title);
-
- buttons.insertBefore(runCodeButton, buttons.firstChild);
- runCodeButton.addEventListener('click', function (e) {
- run_rust_code(pre_block);
- });
-
- if (window.playground_copyable) {
- var copyCodeClipboardButton = document.createElement('button');
- copyCodeClipboardButton.className = 'fa fa-copy clip-button';
- copyCodeClipboardButton.innerHTML = '';
- copyCodeClipboardButton.title = 'Copy to clipboard';
- copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
-
- buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
- }
-
- let code_block = pre_block.querySelector("code");
- if (window.ace && code_block.classList.contains("editable")) {
- var undoChangesButton = document.createElement('button');
- undoChangesButton.className = 'fa fa-history reset-button';
- undoChangesButton.title = 'Undo changes';
- undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
-
- buttons.insertBefore(undoChangesButton, buttons.firstChild);
-
- undoChangesButton.addEventListener('click', function () {
- let editor = window.ace.edit(code_block);
- editor.setValue(editor.originalCode);
- editor.clearSelection();
- });
- }
- });
-})();
-
-(function themes() {
- var html = document.querySelector('html');
- var themeToggleButton = document.getElementById('theme-toggle');
- var themePopup = document.getElementById('theme-list');
- var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
- var stylesheets = {
- ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"),
- tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"),
- highlight: document.querySelector("[href$='highlight.css']"),
- };
-
- function showThemes() {
- themePopup.style.display = 'block';
- themeToggleButton.setAttribute('aria-expanded', true);
- themePopup.querySelector("button#" + get_theme()).focus();
- }
-
- function hideThemes() {
- themePopup.style.display = 'none';
- themeToggleButton.setAttribute('aria-expanded', false);
- themeToggleButton.focus();
- }
-
- function get_theme() {
- var theme;
- try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { }
- if (theme === null || theme === undefined) {
- return default_theme;
- } else {
- return theme;
- }
- }
-
- function set_theme(theme, store = true) {
- let ace_theme;
-
- if (theme == 'coal' || theme == 'navy') {
- stylesheets.ayuHighlight.disabled = true;
- stylesheets.tomorrowNight.disabled = false;
- stylesheets.highlight.disabled = true;
-
- ace_theme = "ace/theme/tomorrow_night";
- } else if (theme == 'ayu') {
- stylesheets.ayuHighlight.disabled = false;
- stylesheets.tomorrowNight.disabled = true;
- stylesheets.highlight.disabled = true;
- ace_theme = "ace/theme/tomorrow_night";
- } else {
- stylesheets.ayuHighlight.disabled = true;
- stylesheets.tomorrowNight.disabled = true;
- stylesheets.highlight.disabled = false;
- ace_theme = "ace/theme/dawn";
- }
-
- setTimeout(function () {
- themeColorMetaTag.content = getComputedStyle(document.body).backgroundColor;
- }, 1);
-
- if (window.ace && window.editors) {
- window.editors.forEach(function (editor) {
- editor.setTheme(ace_theme);
- });
- }
-
- var previousTheme = get_theme();
-
- if (store) {
- try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
- }
-
- html.classList.remove(previousTheme);
- html.classList.add(theme);
- }
-
- // Set theme
- var theme = get_theme();
-
- set_theme(theme, false);
-
- themeToggleButton.addEventListener('click', function () {
- if (themePopup.style.display === 'block') {
- hideThemes();
- } else {
- showThemes();
- }
- });
-
- themePopup.addEventListener('click', function (e) {
- var theme;
- if (e.target.className === "theme") {
- theme = e.target.id;
- } else if (e.target.parentElement.className === "theme") {
- theme = e.target.parentElement.id;
- } else {
- return;
- }
- set_theme(theme);
- });
-
- themePopup.addEventListener('focusout', function(e) {
- // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
- if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) {
- hideThemes();
- }
- });
-
- // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628
- document.addEventListener('click', function(e) {
- if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
- hideThemes();
- }
- });
-
- document.addEventListener('keydown', function (e) {
- if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
- if (!themePopup.contains(e.target)) { return; }
-
- switch (e.key) {
- case 'Escape':
- e.preventDefault();
- hideThemes();
- break;
- case 'ArrowUp':
- e.preventDefault();
- var li = document.activeElement.parentElement;
- if (li && li.previousElementSibling) {
- li.previousElementSibling.querySelector('button').focus();
- }
- break;
- case 'ArrowDown':
- e.preventDefault();
- var li = document.activeElement.parentElement;
- if (li && li.nextElementSibling) {
- li.nextElementSibling.querySelector('button').focus();
- }
- break;
- case 'Home':
- e.preventDefault();
- themePopup.querySelector('li:first-child button').focus();
- break;
- case 'End':
- e.preventDefault();
- themePopup.querySelector('li:last-child button').focus();
- break;
- }
- });
-})();
-
-(function languages() {
- var languageToggleButton = document.getElementById('language-toggle');
- var languagePopup = document.getElementById('language-list');
-
- if (languageToggleButton !== null) {
- function showLanguages() {
- languagePopup.style.display = 'block';
- languageToggleButton.setAttribute('aria-expanded', true);
- }
-
- function hideLanguages() {
- languagePopup.style.display = 'none';
- languageToggleButton.setAttribute('aria-expanded', false);
- languageToggleButton.focus();
- }
-
- function set_language(language) {
- console.log("Set language " + language)
- }
-
- languageToggleButton.addEventListener('click', function () {
- if (languagePopup.style.display === 'block') {
- hideLanguages();
- } else {
- showLanguages();
- }
- });
-
- languagePopup.addEventListener('click', function (e) {
- var language = e.target.id || e.target.parentElement.id;
- set_language(language);
- });
-
- languagePopup.addEventListener('focusout', function(e) {
- // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
- if (!!e.relatedTarget && !languageToggleButton.contains(e.relatedTarget) && !languagePopup.contains(e.relatedTarget)) {
- hideLanguages();
- }
- });
-
- // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628
- document.addEventListener('click', function(e) {
- if (languagePopup.style.display === 'block' && !languageToggleButton.contains(e.target) && !languagePopup.contains(e.target)) {
- hideLanguages();
- }
- });
-
- document.addEventListener('keydown', function (e) {
- if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
- if (!languagePopup.contains(e.target)) { return; }
-
- switch (e.key) {
- case 'Escape':
- e.preventDefault();
- hideLanguages();
- break;
- case 'ArrowUp':
- e.preventDefault();
- var li = document.activeElement.parentElement;
- if (li && li.previousElementSibling) {
- li.previousElementSibling.querySelector('button').focus();
- }
- break;
- case 'ArrowDown':
- e.preventDefault();
- var li = document.activeElement.parentElement;
- if (li && li.nextElementSibling) {
- li.nextElementSibling.querySelector('button').focus();
- }
- break;
- case 'Home':
- e.preventDefault();
- languagePopup.querySelector('li:first-child button').focus();
- break;
- case 'End':
- e.preventDefault();
- languagePopup.querySelector('li:last-child button').focus();
- break;
- }
- });
- }
-})();
-
-(function sidebar() {
- var html = document.querySelector("html");
- var sidebar = document.getElementById("sidebar");
- var sidebarLinks = document.querySelectorAll('#sidebar a');
- var sidebarToggleButton = document.getElementById("sidebar-toggle");
- var sidebarResizeHandle = document.getElementById("sidebar-resize-handle");
- var firstContact = null;
-
- function showSidebar() {
- html.classList.remove('sidebar-hidden')
- html.classList.add('sidebar-visible');
- Array.from(sidebarLinks).forEach(function (link) {
- link.setAttribute('tabIndex', 0);
- });
- sidebarToggleButton.setAttribute('aria-expanded', true);
- sidebar.setAttribute('aria-hidden', false);
- try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
- }
-
-
- var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle');
-
- function toggleSection(ev) {
- ev.currentTarget.parentElement.classList.toggle('expanded');
- }
-
- Array.from(sidebarAnchorToggles).forEach(function (el) {
- el.addEventListener('click', toggleSection);
- });
-
- function hideSidebar() {
- html.classList.remove('sidebar-visible')
- html.classList.add('sidebar-hidden');
- Array.from(sidebarLinks).forEach(function (link) {
- link.setAttribute('tabIndex', -1);
- });
- sidebarToggleButton.setAttribute('aria-expanded', false);
- sidebar.setAttribute('aria-hidden', true);
- try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
- }
-
- // Toggle sidebar
- sidebarToggleButton.addEventListener('click', function sidebarToggle() {
- if (html.classList.contains("sidebar-hidden")) {
- var current_width = parseInt(
- document.documentElement.style.getPropertyValue('--sidebar-width'), 10);
- if (current_width < 150) {
- document.documentElement.style.setProperty('--sidebar-width', '150px');
- }
- showSidebar();
- } else if (html.classList.contains("sidebar-visible")) {
- hideSidebar();
- } else {
- if (getComputedStyle(sidebar)['transform'] === 'none') {
- hideSidebar();
- } else {
- showSidebar();
- }
- }
- });
-
- sidebarResizeHandle.addEventListener('mousedown', initResize, false);
-
- function initResize(e) {
- window.addEventListener('mousemove', resize, false);
- window.addEventListener('mouseup', stopResize, false);
- html.classList.add('sidebar-resizing');
- }
- function resize(e) {
- var pos = (e.clientX - sidebar.offsetLeft);
- if (pos < 20) {
- hideSidebar();
- } else {
- if (html.classList.contains("sidebar-hidden")) {
- showSidebar();
- }
- pos = Math.min(pos, window.innerWidth - 100);
- document.documentElement.style.setProperty('--sidebar-width', pos + 'px');
- }
- }
- //on mouseup remove windows functions mousemove & mouseup
- function stopResize(e) {
- html.classList.remove('sidebar-resizing');
- window.removeEventListener('mousemove', resize, false);
- window.removeEventListener('mouseup', stopResize, false);
- }
-
- document.addEventListener('touchstart', function (e) {
- firstContact = {
- x: e.touches[0].clientX,
- time: Date.now()
- };
- }, { passive: true });
-
- document.addEventListener('touchmove', function (e) {
- if (!firstContact)
- return;
-
- var curX = e.touches[0].clientX;
- var xDiff = curX - firstContact.x,
- tDiff = Date.now() - firstContact.time;
-
- if (tDiff < 250 && Math.abs(xDiff) >= 150) {
- if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
- showSidebar();
- else if (xDiff < 0 && curX < 300)
- hideSidebar();
-
- firstContact = null;
- }
- }, { passive: true });
-
- // Scroll sidebar to current active section
- var activeSection = document.getElementById("sidebar").querySelector(".active");
- if (activeSection) {
- // https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView
- activeSection.scrollIntoView({ block: 'center' });
- }
-})();
-
-(function chapterNavigation() {
- document.addEventListener('keydown', function (e) {
- if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
- if (window.search && window.search.hasFocus()) { return; }
-
- switch (e.key) {
- case 'ArrowRight':
- e.preventDefault();
- var nextButton = document.querySelector('.nav-chapters.next');
- if (nextButton) {
- window.location.href = nextButton.href;
- }
- break;
- case 'ArrowLeft':
- e.preventDefault();
- var previousButton = document.querySelector('.nav-chapters.previous');
- if (previousButton) {
- window.location.href = previousButton.href;
- }
- break;
- }
- });
-})();
-
-(function clipboard() {
- var clipButtons = document.querySelectorAll('.clip-button');
-
- function hideTooltip(elem) {
- elem.firstChild.innerText = "";
- elem.className = 'fa fa-copy clip-button';
- }
-
- function showTooltip(elem, msg) {
- elem.firstChild.innerText = msg;
- elem.className = 'fa fa-copy tooltipped';
- }
-
- var clipboardSnippets = new ClipboardJS('.clip-button', {
- text: function (trigger) {
- hideTooltip(trigger);
- let playground = trigger.closest("pre");
- return playground_text(playground);
- }
- });
-
- Array.from(clipButtons).forEach(function (clipButton) {
- clipButton.addEventListener('mouseout', function (e) {
- hideTooltip(e.currentTarget);
- });
- });
-
- clipboardSnippets.on('success', function (e) {
- e.clearSelection();
- showTooltip(e.trigger, "Copied!");
- });
-
- clipboardSnippets.on('error', function (e) {
- showTooltip(e.trigger, "Clipboard error!");
- });
-})();
-
-(function scrollToTop () {
- var menuTitle = document.querySelector('.menu-title');
-
- menuTitle.addEventListener('click', function () {
- document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
- });
-})();
-
-(function controllMenu() {
- var menu = document.getElementById('menu-bar');
-
- (function controllPosition() {
- var scrollTop = document.scrollingElement.scrollTop;
- var prevScrollTop = scrollTop;
- var minMenuY = -menu.clientHeight - 50;
- // When the script loads, the page can be at any scroll (e.g. if you reforesh it).
- menu.style.top = scrollTop + 'px';
- // Same as parseInt(menu.style.top.slice(0, -2), but faster
- var topCache = menu.style.top.slice(0, -2);
- menu.classList.remove('sticky');
- var stickyCache = false; // Same as menu.classList.contains('sticky'), but faster
- document.addEventListener('scroll', function () {
- scrollTop = Math.max(document.scrollingElement.scrollTop, 0);
- // `null` means that it doesn't need to be updated
- var nextSticky = null;
- var nextTop = null;
- var scrollDown = scrollTop > prevScrollTop;
- var menuPosAbsoluteY = topCache - scrollTop;
- if (scrollDown) {
- nextSticky = false;
- if (menuPosAbsoluteY > 0) {
- nextTop = prevScrollTop;
- }
- } else {
- if (menuPosAbsoluteY > 0) {
- nextSticky = true;
- } else if (menuPosAbsoluteY < minMenuY) {
- nextTop = prevScrollTop + minMenuY;
- }
- }
- if (nextSticky === true && stickyCache === false) {
- menu.classList.add('sticky');
- stickyCache = true;
- } else if (nextSticky === false && stickyCache === true) {
- menu.classList.remove('sticky');
- stickyCache = false;
- }
- if (nextTop !== null) {
- menu.style.top = nextTop + 'px';
- topCache = nextTop;
- }
- prevScrollTop = scrollTop;
- }, { passive: true });
- })();
- (function controllBorder() {
- menu.classList.remove('bordered');
- document.addEventListener('scroll', function () {
- if (menu.offsetTop === 0) {
- menu.classList.remove('bordered');
- } else {
- menu.classList.add('bordered');
- }
- }, { passive: true });
- })();
-})();
diff --git a/docs/nightly/guide/en/clipboard.min.js b/docs/nightly/guide/en/clipboard.min.js
deleted file mode 100644
index 02c549e35..000000000
--- a/docs/nightly/guide/en/clipboard.min.js
+++ /dev/null
@@ -1,7 +0,0 @@
-/*!
- * clipboard.js v2.0.4
- * https://zenorocha.github.io/clipboard.js
- *
- * Licensed MIT © Zeno Rocha
- */
-!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.ClipboardJS=e():t.ClipboardJS=e()}(this,function(){return function(n){var o={};function r(t){if(o[t])return o[t].exports;var e=o[t]={i:t,l:!1,exports:{}};return n[t].call(e.exports,e,e.exports,r),e.l=!0,e.exports}return r.m=n,r.c=o,r.d=function(t,e,n){r.o(t,e)||Object.defineProperty(t,e,{enumerable:!0,get:n})},r.r=function(t){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(t,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(t,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(t){var e=t&&t.__esModule?function(){return t.default}:function(){return t};return r.d(e,"a",e),e},r.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},r.p="",r(r.s=0)}([function(t,e,n){"use strict";var r="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},i=function(){function o(t,e){for(var n=0;n
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- 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 -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/contributing/index.html b/docs/nightly/guide/en/contributing/index.html
deleted file mode 100644
index 081c82653..000000000
--- a/docs/nightly/guide/en/contributing/index.html
+++ /dev/null
@@ -1,255 +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.hookprovides 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. -
- - Hooks: the hooks crate has the most common use cases, but
-
-
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 -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/contributing/project_structure.html b/docs/nightly/guide/en/contributing/project_structure.html
deleted file mode 100644
index fb9c4cd39..000000000
--- a/docs/nightly/guide/en/contributing/project_structure.html
+++ /dev/null
@@ -1,273 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Contributing
-Development happens in the Dioxus GitHub repository. 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).
-GitHub discussions can be used as a place to ask for help or talk about features. You can also join our Discord channel where some development discussion happens.
-Improving Docs
-If you'd like to improve the docs, PRs are welcome! Both Rust docs (source) and this guide (source) 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 for inspiration. Once you are done, add your library to the awesome dioxus list or share it in the #I-made-a-thing channel on Discord.
Bugs & Features
-If you've fixed an open issue, feel free to submit a PR! You can also take a look at the roadmap and work on something in there. Consider reaching out 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 -
cargo fmt --all
--
-
- All code is formatted with rustfmt -
cargo check --workspace --examples --tests
--
-
- All code is linted with Clippy -
cargo clippy --workspace --examples --tests -- -D warnings
--
-
- Crates that use unsafe are checked for undefined behavior with 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-coreanddioxus-native-core.
-
cargo miri test --package dioxus-core --test miri_stress
-cargo miri test --package dioxus-native-core --test miri_native
--
-
- Rust analyzer can be very helpful for quick feedback in your IDE. -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/contributing/roadmap.html b/docs/nightly/guide/en/contributing/roadmap.html
deleted file mode 100644
index 9fe99cfc7..000000000
--- a/docs/nightly/guide/en/contributing/roadmap.html
+++ /dev/null
@@ -1,380 +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: A Render that Runs Dioxus applications natively, but renders them with the system webview -
- Mobile: A Render that Runs Dioxus applications natively, but renders them with the system webview. This is currently a copy of the desktop render -
- Web: Renders Dioxus applications in the browser by compiling to WASM and manipulating the DOM -
- Liveview: A Render that Runs on the server, and renders using a websocket proxy in the browser -
- Rink: A Renderer that renders a HTML-like tree into a terminal -
- TUI: A Renderer that uses Rink to render a Dioxus application in a terminal -
- Blitz-Core: An experimental native renderer that renders a HTML-like tree using WGPU. -
- Blitz: An experimental native renderer that uses Blitz-Core to render a Dioxus application using WGPU. -
- SSR: A Render that Runs Dioxus applications on the server, and renders them to HTML -
State Management/Hooks
--
-
- Hooks: A collection of common hooks for Dioxus applications -
- Signals: A experimental state management library for Dioxus applications. This currently contains a
Copyversion of UseRef
- - Dioxus STD: A collection of platform agnostic hooks to interact with system interfaces (The clipboard, camera, etc.). -
- Fermi: A global state management library for Dioxus applications. -Router: A client-side router for Dioxus applications -
Core utilities
--
-
- core: The core virtual dom implementation every Dioxus application uses
-
-
-
- You can read more about the archetecture of the core in this blog post and the custom renderer section of the guide -
- - RSX: The core parsing for RSX used for hot reloading, autoformatting, and the macro -
- core-macro: The rsx! macro used to write Dioxus applications. (This is a wrapper over the RSX crate) -
- HTML macro: A html-like alternative to the RSX macro -
Native Renderer Utilities
--
-
- 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 -
- - native-core-macro: A helper macro for native core -
- Taffy: Layout engine powering Blitz-Core, Rink, and Bevy UI -
Web renderer tooling
--
-
- HTML: defines html specific elements, events, and attributes -
- Interpreter: defines browser bindings used by the web and desktop renderers -
Developer tooling
--
-
- 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 -
- autofmt: Formats RSX code -
- rsx-rosetta: Handles conversion between HTML and RSX -
- CLI: A Command Line Interface and VSCode extension to assist with Dioxus usage -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/contributing/walkthrough_readme.html b/docs/nightly/guide/en/contributing/walkthrough_readme.html
deleted file mode 100644
index 09bc4afae..000000000
--- a/docs/nightly/guide/en/contributing/walkthrough_readme.html
+++ /dev/null
@@ -1,433 +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.
-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
--
-
- -Release of Dioxus Core -
- -Upgrade documentation to include more theory and be more comprehensive -
- -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
--
-
- -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)
--
-
- -Translation from HTML into RSX -
- -Dev server -
- -Live reload -
- -Translation from JSX into RSX -
- -Hot module replacement -
- -Code splitting -
- -Asset macros -
- -Css pipeline -
- -Image pipeline -
Essential hooks
--
-
- -Router -
- -Global state management -
- -Resize observer -
Work in Progress
-Build Tool
-We are currently working on our own build tool called Dioxus 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. This will allow you to build apps that are rendered natively for iOS, Android, and Desktop.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/css/chrome.css b/docs/nightly/guide/en/css/chrome.css
deleted file mode 100644
index 0ed18a02f..000000000
--- a/docs/nightly/guide/en/css/chrome.css
+++ /dev/null
@@ -1,542 +0,0 @@
-/* CSS for UI elements (a.k.a. chrome) */
-
-@import 'variables.css';
-
-::-webkit-scrollbar {
- background: var(--bg);
-}
-::-webkit-scrollbar-thumb {
- background: var(--scrollbar);
-}
-html {
- scrollbar-color: var(--scrollbar) var(--bg);
-}
-#searchresults a,
-.content a:link,
-a:visited,
-a > .hljs {
- color: var(--links);
-}
-
-/* Menu Bar */
-
-#menu-bar,
-#menu-bar-hover-placeholder {
- z-index: 101;
- margin: auto calc(0px - var(--page-padding));
-}
-#menu-bar {
- position: relative;
- display: flex;
- flex-wrap: wrap;
- background-color: var(--bg);
- border-bottom-color: var(--bg);
- border-bottom-width: 1px;
- border-bottom-style: solid;
-}
-#menu-bar.sticky,
-.js #menu-bar-hover-placeholder:hover + #menu-bar,
-.js #menu-bar:hover,
-.js.sidebar-visible #menu-bar {
- position: -webkit-sticky;
- position: sticky;
- top: 0 !important;
-}
-#menu-bar-hover-placeholder {
- position: sticky;
- position: -webkit-sticky;
- top: 0;
- height: var(--menu-bar-height);
-}
-#menu-bar.bordered {
- border-bottom-color: var(--table-border-color);
-}
-#menu-bar i, #menu-bar .icon-button {
- position: relative;
- padding: 0 8px;
- z-index: 10;
- line-height: var(--menu-bar-height);
- cursor: pointer;
- transition: color 0.5s;
-}
-@media only screen and (max-width: 420px) {
- #menu-bar i, #menu-bar .icon-button {
- padding: 0 5px;
- }
-}
-
-.icon-button {
- border: none;
- background: none;
- padding: 0;
- color: inherit;
-}
-.icon-button i {
- margin: 0;
-}
-
-.right-buttons {
- margin: 0 15px;
-}
-.right-buttons a {
- text-decoration: none;
-}
-
-.left-buttons {
- display: flex;
- margin: 0 5px;
-}
-.no-js .left-buttons {
- display: none;
-}
-
-.menu-title {
- display: inline-block;
- font-weight: 200;
- font-size: 2.4rem;
- line-height: var(--menu-bar-height);
- text-align: center;
- margin: 0;
- flex: 1;
- white-space: nowrap;
- overflow: hidden;
- text-overflow: ellipsis;
-}
-.js .menu-title {
- cursor: pointer;
-}
-
-.menu-bar,
-.menu-bar:visited,
-.nav-chapters,
-.nav-chapters:visited,
-.mobile-nav-chapters,
-.mobile-nav-chapters:visited,
-.menu-bar .icon-button,
-.menu-bar a i {
- color: var(--icons);
-}
-
-.menu-bar i:hover,
-.menu-bar .icon-button:hover,
-.nav-chapters:hover,
-.mobile-nav-chapters i:hover {
- color: var(--icons-hover);
-}
-
-/* Nav Icons */
-
-.nav-chapters {
- font-size: 2.5em;
- text-align: center;
- text-decoration: none;
-
- position: fixed;
- top: 0;
- bottom: 0;
- margin: 0;
- max-width: 150px;
- min-width: 90px;
-
- display: flex;
- justify-content: center;
- align-content: center;
- flex-direction: column;
-
- transition: color 0.5s, background-color 0.5s;
-}
-
-.nav-chapters:hover {
- text-decoration: none;
- background-color: var(--theme-hover);
- transition: background-color 0.15s, color 0.15s;
-}
-
-.nav-wrapper {
- margin-top: 50px;
- display: none;
-}
-
-.mobile-nav-chapters {
- font-size: 2.5em;
- text-align: center;
- text-decoration: none;
- width: 90px;
- border-radius: 5px;
- background-color: var(--sidebar-bg);
-}
-
-.previous {
- float: left;
-}
-
-.next {
- float: right;
- right: var(--page-padding);
-}
-
-@media only screen and (max-width: 1080px) {
- .nav-wide-wrapper { display: none; }
- .nav-wrapper { display: block; }
-}
-
-@media only screen and (max-width: 1380px) {
- .sidebar-visible .nav-wide-wrapper { display: none; }
- .sidebar-visible .nav-wrapper { display: block; }
-}
-
-/* Inline code */
-
-:not(pre) > .hljs {
- display: inline;
- padding: 0.1em 0.3em;
- border-radius: 3px;
-}
-
-:not(pre):not(a) > .hljs {
- color: var(--inline-code-color);
- overflow-x: initial;
-}
-
-a:hover > .hljs {
- text-decoration: underline;
-}
-
-pre {
- position: relative;
-}
-pre > .buttons {
- position: absolute;
- z-index: 100;
- right: 5px;
- top: 5px;
-
- color: var(--sidebar-fg);
- cursor: pointer;
-}
-pre > .buttons :hover {
- color: var(--sidebar-active);
-}
-pre > .buttons i {
- margin-left: 8px;
-}
-pre > .buttons button {
- color: inherit;
- background: transparent;
- border: none;
- cursor: inherit;
-}
-pre > .result {
- margin-top: 10px;
-}
-
-/* Search */
-
-#searchresults a {
- text-decoration: none;
-}
-
-mark {
- border-radius: 2px;
- padding: 0 3px 1px 3px;
- margin: 0 -3px -1px -3px;
- background-color: var(--search-mark-bg);
- transition: background-color 300ms linear;
- cursor: pointer;
-}
-
-mark.fade-out {
- background-color: rgba(0,0,0,0) !important;
- cursor: auto;
-}
-
-.searchbar-outer {
- margin-left: auto;
- margin-right: auto;
- max-width: var(--content-max-width);
-}
-
-#searchbar {
- width: 100%;
- margin: 5px auto 0px auto;
- padding: 10px 16px;
- transition: box-shadow 300ms ease-in-out;
- border: 1px solid var(--searchbar-border-color);
- border-radius: 3px;
- background-color: var(--searchbar-bg);
- color: var(--searchbar-fg);
-}
-#searchbar:focus,
-#searchbar.active {
- box-shadow: 0 0 3px var(--searchbar-shadow-color);
-}
-
-.searchresults-header {
- font-weight: bold;
- font-size: 1em;
- padding: 18px 0 0 5px;
- color: var(--searchresults-header-fg);
-}
-
-.searchresults-outer {
- margin-left: auto;
- margin-right: auto;
- max-width: var(--content-max-width);
- border-bottom: 1px dashed var(--searchresults-border-color);
-}
-
-ul#searchresults {
- list-style: none;
- padding-left: 20px;
-}
-ul#searchresults li {
- margin: 10px 0px;
- padding: 2px;
- border-radius: 2px;
-}
-ul#searchresults li.focus {
- background-color: var(--searchresults-li-bg);
-}
-ul#searchresults span.teaser {
- display: block;
- clear: both;
- margin: 5px 0 0 20px;
- font-size: 0.8em;
-}
-ul#searchresults span.teaser em {
- font-weight: bold;
- font-style: normal;
-}
-
-/* Sidebar */
-
-.sidebar {
- position: fixed;
- left: 0;
- top: 0;
- bottom: 0;
- width: var(--sidebar-width);
- font-size: 0.875em;
- box-sizing: border-box;
- -webkit-overflow-scrolling: touch;
- overscroll-behavior-y: contain;
- background-color: var(--sidebar-bg);
- color: var(--sidebar-fg);
-}
-.sidebar-resizing {
- -moz-user-select: none;
- -webkit-user-select: none;
- -ms-user-select: none;
- user-select: none;
-}
-.js:not(.sidebar-resizing) .sidebar {
- transition: transform 0.3s; /* Animation: slide away */
-}
-.sidebar code {
- line-height: 2em;
-}
-.sidebar .sidebar-scrollbox {
- overflow-y: auto;
- position: absolute;
- top: 0;
- bottom: 0;
- left: 0;
- right: 0;
- padding: 10px 10px;
-}
-.sidebar .sidebar-resize-handle {
- position: absolute;
- cursor: col-resize;
- width: 0;
- right: 0;
- top: 0;
- bottom: 0;
-}
-.js .sidebar .sidebar-resize-handle {
- cursor: col-resize;
- width: 5px;
-}
-.sidebar-hidden .sidebar {
- transform: translateX(calc(0px - var(--sidebar-width)));
-}
-.sidebar::-webkit-scrollbar {
- background: var(--sidebar-bg);
-}
-.sidebar::-webkit-scrollbar-thumb {
- background: var(--scrollbar);
-}
-
-.sidebar-visible .page-wrapper {
- transform: translateX(var(--sidebar-width));
-}
-@media only screen and (min-width: 620px) {
- .sidebar-visible .page-wrapper {
- transform: none;
- margin-left: var(--sidebar-width);
- }
-}
-
-.chapter {
- list-style: none outside none;
- padding-left: 0;
- line-height: 2.2em;
-}
-
-.chapter ol {
- width: 100%;
-}
-
-.chapter li {
- display: flex;
- color: var(--sidebar-non-existant);
-}
-.chapter li a {
- display: block;
- padding: 0;
- text-decoration: none;
- color: var(--sidebar-fg);
-}
-
-.chapter li a:hover {
- color: var(--sidebar-active);
-}
-
-.chapter li a.active {
- color: var(--sidebar-active);
-}
-
-.chapter li > a.toggle {
- cursor: pointer;
- display: block;
- margin-left: auto;
- padding: 0 10px;
- user-select: none;
- opacity: 0.68;
-}
-
-.chapter li > a.toggle div {
- transition: transform 0.5s;
-}
-
-/* collapse the section */
-.chapter li:not(.expanded) + li > ol {
- display: none;
-}
-
-.chapter li.chapter-item {
- line-height: 1.5em;
- margin-top: 0.6em;
-}
-
-.chapter li.expanded > a.toggle div {
- transform: rotate(90deg);
-}
-
-.spacer {
- width: 100%;
- height: 3px;
- margin: 5px 0px;
-}
-.chapter .spacer {
- background-color: var(--sidebar-spacer);
-}
-
-@media (-moz-touch-enabled: 1), (pointer: coarse) {
- .chapter li a { padding: 5px 0; }
- .spacer { margin: 10px 0; }
-}
-
-.section {
- list-style: none outside none;
- padding-left: 20px;
- line-height: 1.9em;
-}
-
-/* Theme Menu Popup */
-
-.theme-popup {
- position: absolute;
- left: 10px;
- top: var(--menu-bar-height);
- z-index: 1000;
- border-radius: 4px;
- font-size: 0.7em;
- color: var(--fg);
- background: var(--theme-popup-bg);
- border: 1px solid var(--theme-popup-border);
- margin: 0;
- padding: 0;
- list-style: none;
- display: none;
-}
-.theme-popup .default {
- color: var(--icons);
-}
-.theme-popup .theme {
- width: 100%;
- border: 0;
- margin: 0;
- padding: 2px 10px;
- line-height: 25px;
- white-space: nowrap;
- text-align: left;
- cursor: pointer;
- color: inherit;
- background: inherit;
- font-size: inherit;
-}
-.theme-popup .theme:hover {
- background-color: var(--theme-hover);
-}
-.theme-popup .theme:hover:first-child,
-.theme-popup .theme:hover:last-child {
- border-top-left-radius: inherit;
- border-top-right-radius: inherit;
-}
-
-/* Language Menu Popup */
-
-.language-popup {
- position: absolute;
- left: 150px;
- top: var(--menu-bar-height);
- z-index: 1000;
- border-radius: 4px;
- font-size: 0.7em;
- color: var(--fg);
- background: var(--theme-popup-bg);
- border: 1px solid var(--theme-popup-border);
- margin: 0;
- padding: 0;
- list-style: none;
- display: none;
-}
-.language-popup .default {
- color: var(--icons);
-}
-.language-popup .language {
- width: 100%;
- border: 0;
- margin: 0;
- padding: 2px 10px;
- line-height: 25px;
- white-space: nowrap;
- text-align: left;
- cursor: pointer;
- color: inherit;
- background: inherit;
- font-size: inherit;
-}
-.language-popup .language:hover {
- background-color: var(--theme-hover);
-}
-.language-popup .language:hover:first-child,
-.language-popup .language:hover:last-child {
- border-top-left-radius: inherit;
- border-top-right-radius: inherit;
-}
-
-.language-popup a {
- color: var(--fg);
- text-decoration: none;
-}
diff --git a/docs/nightly/guide/en/css/general.css b/docs/nightly/guide/en/css/general.css
deleted file mode 100644
index ef2ba5048..000000000
--- a/docs/nightly/guide/en/css/general.css
+++ /dev/null
@@ -1,182 +0,0 @@
-/* Base styles and content styles */
-
-@import 'variables.css';
-
-:root {
- /* Browser default font-size is 16px, this way 1 rem = 10px */
- font-size: 62.5%;
-}
-
-html {
- font-family: "Open Sans", sans-serif;
- color: var(--fg);
- background-color: var(--bg);
- text-size-adjust: none;
- -webkit-text-size-adjust: none;
-}
-
-body {
- margin: 0;
- font-size: 1.6rem;
- overflow-x: hidden;
-}
-
-code {
- font-family: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace !important;
- font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */
-}
-
-/* Don't change font size in headers. */
-h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
- font-size: unset;
-}
-
-.left { float: left; }
-.right { float: right; }
-.boring { opacity: 0.6; }
-.hide-boring .boring { display: none; }
-.hidden { display: none !important; }
-
-h2, h3 { margin-top: 2.5em; }
-h4, h5 { margin-top: 2em; }
-
-.header + .header h3,
-.header + .header h4,
-.header + .header h5 {
- margin-top: 1em;
-}
-
-h1:target::before,
-h2:target::before,
-h3:target::before,
-h4:target::before,
-h5:target::before,
-h6:target::before {
- display: inline-block;
- content: "»";
- margin-left: -30px;
- width: 30px;
-}
-
-/* This is broken on Safari as of version 14, but is fixed
- in Safari Technology Preview 117 which I think will be Safari 14.2.
- https://bugs.webkit.org/show_bug.cgi?id=218076
-*/
-:target {
- scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
-}
-
-.page {
- outline: 0;
- padding: 0 var(--page-padding);
- margin-top: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
-}
-.page-wrapper {
- box-sizing: border-box;
-}
-.js:not(.sidebar-resizing) .page-wrapper {
- transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
-}
-
-.content {
- overflow-y: auto;
- padding: 0 15px;
- padding-bottom: 50px;
-}
-.content main {
- margin-left: auto;
- margin-right: auto;
- max-width: var(--content-max-width);
-}
-.content p { line-height: 1.45em; }
-.content ol { line-height: 1.45em; }
-.content ul { line-height: 1.45em; }
-.content a { text-decoration: none; }
-.content a:hover { text-decoration: underline; }
-.content img, .content video { max-width: 100%; }
-.content .header:link,
-.content .header:visited {
- color: var(--fg);
-}
-.content .header:link,
-.content .header:visited:hover {
- text-decoration: none;
-}
-
-table {
- margin: 0 auto;
- border-collapse: collapse;
-}
-table td {
- padding: 3px 20px;
- border: 1px var(--table-border-color) solid;
-}
-table thead {
- background: var(--table-header-bg);
-}
-table thead td {
- font-weight: 700;
- border: none;
-}
-table thead th {
- padding: 3px 20px;
-}
-table thead tr {
- border: 1px var(--table-header-bg) solid;
-}
-/* Alternate background colors for rows */
-table tbody tr:nth-child(2n) {
- background: var(--table-alternate-bg);
-}
-
-
-blockquote {
- margin: 20px 0;
- padding: 0 20px;
- color: var(--fg);
- background-color: var(--quote-bg);
- border-top: .1em solid var(--quote-border);
- border-bottom: .1em solid var(--quote-border);
-}
-
-
-:not(.footnote-definition) + .footnote-definition,
-.footnote-definition + :not(.footnote-definition) {
- margin-top: 2em;
-}
-.footnote-definition {
- font-size: 0.9em;
- margin: 0.5em 0;
-}
-.footnote-definition p {
- display: inline;
-}
-
-.tooltiptext {
- position: absolute;
- visibility: hidden;
- color: #fff;
- background-color: #333;
- transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
- left: -8px; /* Half of the width of the icon */
- top: -35px;
- font-size: 0.8em;
- text-align: center;
- border-radius: 6px;
- padding: 5px 8px;
- margin: 5px;
- z-index: 1000;
-}
-.tooltipped .tooltiptext {
- visibility: visible;
-}
-
-.chapter li.part-title {
- color: var(--sidebar-fg);
- margin: 5px 0px;
- font-weight: bold;
-}
-
-.result-no-output {
- font-style: italic;
-}
diff --git a/docs/nightly/guide/en/css/print.css b/docs/nightly/guide/en/css/print.css
deleted file mode 100644
index 5e690f755..000000000
--- a/docs/nightly/guide/en/css/print.css
+++ /dev/null
@@ -1,54 +0,0 @@
-
-#sidebar,
-#menu-bar,
-.nav-chapters,
-.mobile-nav-chapters {
- display: none;
-}
-
-#page-wrapper.page-wrapper {
- transform: none;
- margin-left: 0px;
- overflow-y: initial;
-}
-
-#content {
- max-width: none;
- margin: 0;
- padding: 0;
-}
-
-.page {
- overflow-y: initial;
-}
-
-code {
- background-color: #666666;
- border-radius: 5px;
-
- /* Force background to be printed in Chrome */
- -webkit-print-color-adjust: exact;
-}
-
-pre > .buttons {
- z-index: 2;
-}
-
-a, a:visited, a:active, a:hover {
- color: #4183c4;
- text-decoration: none;
-}
-
-h1, h2, h3, h4, h5, h6 {
- page-break-inside: avoid;
- page-break-after: avoid;
-}
-
-pre, code {
- page-break-inside: avoid;
- white-space: pre-wrap;
-}
-
-.fa {
- display: none !important;
-}
diff --git a/docs/nightly/guide/en/css/variables.css b/docs/nightly/guide/en/css/variables.css
deleted file mode 100644
index 56b634bc3..000000000
--- a/docs/nightly/guide/en/css/variables.css
+++ /dev/null
@@ -1,253 +0,0 @@
-
-/* Globals */
-
-:root {
- --sidebar-width: 300px;
- --page-padding: 15px;
- --content-max-width: 750px;
- --menu-bar-height: 50px;
-}
-
-/* Themes */
-
-.ayu {
- --bg: hsl(210, 25%, 8%);
- --fg: #c5c5c5;
-
- --sidebar-bg: #14191f;
- --sidebar-fg: #c8c9db;
- --sidebar-non-existant: #5c6773;
- --sidebar-active: #ffb454;
- --sidebar-spacer: #2d334f;
-
- --scrollbar: var(--sidebar-fg);
-
- --icons: #737480;
- --icons-hover: #b7b9cc;
-
- --links: #0096cf;
-
- --inline-code-color: #ffb454;
-
- --theme-popup-bg: #14191f;
- --theme-popup-border: #5c6773;
- --theme-hover: #191f26;
-
- --quote-bg: hsl(226, 15%, 17%);
- --quote-border: hsl(226, 15%, 22%);
-
- --table-border-color: hsl(210, 25%, 13%);
- --table-header-bg: hsl(210, 25%, 28%);
- --table-alternate-bg: hsl(210, 25%, 11%);
-
- --searchbar-border-color: #848484;
- --searchbar-bg: #424242;
- --searchbar-fg: #fff;
- --searchbar-shadow-color: #d4c89f;
- --searchresults-header-fg: #666;
- --searchresults-border-color: #888;
- --searchresults-li-bg: #252932;
- --search-mark-bg: #e3b171;
-}
-
-.coal {
- --bg: hsl(200, 7%, 8%);
- --fg: #98a3ad;
-
- --sidebar-bg: #292c2f;
- --sidebar-fg: #a1adb8;
- --sidebar-non-existant: #505254;
- --sidebar-active: #3473ad;
- --sidebar-spacer: #393939;
-
- --scrollbar: var(--sidebar-fg);
-
- --icons: #43484d;
- --icons-hover: #b3c0cc;
-
- --links: #2b79a2;
-
- --inline-code-color: #c5c8c6;
-
- --theme-popup-bg: #141617;
- --theme-popup-border: #43484d;
- --theme-hover: #1f2124;
-
- --quote-bg: hsl(234, 21%, 18%);
- --quote-border: hsl(234, 21%, 23%);
-
- --table-border-color: hsl(200, 7%, 13%);
- --table-header-bg: hsl(200, 7%, 28%);
- --table-alternate-bg: hsl(200, 7%, 11%);
-
- --searchbar-border-color: #aaa;
- --searchbar-bg: #b7b7b7;
- --searchbar-fg: #000;
- --searchbar-shadow-color: #aaa;
- --searchresults-header-fg: #666;
- --searchresults-border-color: #98a3ad;
- --searchresults-li-bg: #2b2b2f;
- --search-mark-bg: #355c7d;
-}
-
-.light {
- --bg: hsl(0, 0%, 100%);
- --fg: hsl(0, 0%, 0%);
-
- --sidebar-bg: #fafafa;
- --sidebar-fg: hsl(0, 0%, 0%);
- --sidebar-non-existant: #aaaaaa;
- --sidebar-active: #1f1fff;
- --sidebar-spacer: #f4f4f4;
-
- --scrollbar: #8F8F8F;
-
- --icons: #747474;
- --icons-hover: #000000;
-
- --links: #20609f;
-
- --inline-code-color: #301900;
-
- --theme-popup-bg: #fafafa;
- --theme-popup-border: #cccccc;
- --theme-hover: #e6e6e6;
-
- --quote-bg: hsl(197, 37%, 96%);
- --quote-border: hsl(197, 37%, 91%);
-
- --table-border-color: hsl(0, 0%, 95%);
- --table-header-bg: hsl(0, 0%, 80%);
- --table-alternate-bg: hsl(0, 0%, 97%);
-
- --searchbar-border-color: #aaa;
- --searchbar-bg: #fafafa;
- --searchbar-fg: #000;
- --searchbar-shadow-color: #aaa;
- --searchresults-header-fg: #666;
- --searchresults-border-color: #888;
- --searchresults-li-bg: #e4f2fe;
- --search-mark-bg: #a2cff5;
-}
-
-.navy {
- --bg: hsl(226, 23%, 11%);
- --fg: #bcbdd0;
-
- --sidebar-bg: #282d3f;
- --sidebar-fg: #c8c9db;
- --sidebar-non-existant: #505274;
- --sidebar-active: #2b79a2;
- --sidebar-spacer: #2d334f;
-
- --scrollbar: var(--sidebar-fg);
-
- --icons: #737480;
- --icons-hover: #b7b9cc;
-
- --links: #2b79a2;
-
- --inline-code-color: #c5c8c6;
-
- --theme-popup-bg: #161923;
- --theme-popup-border: #737480;
- --theme-hover: #282e40;
-
- --quote-bg: hsl(226, 15%, 17%);
- --quote-border: hsl(226, 15%, 22%);
-
- --table-border-color: hsl(226, 23%, 16%);
- --table-header-bg: hsl(226, 23%, 31%);
- --table-alternate-bg: hsl(226, 23%, 14%);
-
- --searchbar-border-color: #aaa;
- --searchbar-bg: #aeaec6;
- --searchbar-fg: #000;
- --searchbar-shadow-color: #aaa;
- --searchresults-header-fg: #5f5f71;
- --searchresults-border-color: #5c5c68;
- --searchresults-li-bg: #242430;
- --search-mark-bg: #a2cff5;
-}
-
-.rust {
- --bg: hsl(60, 9%, 87%);
- --fg: #262625;
-
- --sidebar-bg: #3b2e2a;
- --sidebar-fg: #c8c9db;
- --sidebar-non-existant: #505254;
- --sidebar-active: #e69f67;
- --sidebar-spacer: #45373a;
-
- --scrollbar: var(--sidebar-fg);
-
- --icons: #737480;
- --icons-hover: #262625;
-
- --links: #2b79a2;
-
- --inline-code-color: #6e6b5e;
-
- --theme-popup-bg: #e1e1db;
- --theme-popup-border: #b38f6b;
- --theme-hover: #99908a;
-
- --quote-bg: hsl(60, 5%, 75%);
- --quote-border: hsl(60, 5%, 70%);
-
- --table-border-color: hsl(60, 9%, 82%);
- --table-header-bg: #b3a497;
- --table-alternate-bg: hsl(60, 9%, 84%);
-
- --searchbar-border-color: #aaa;
- --searchbar-bg: #fafafa;
- --searchbar-fg: #000;
- --searchbar-shadow-color: #aaa;
- --searchresults-header-fg: #666;
- --searchresults-border-color: #888;
- --searchresults-li-bg: #dec2a2;
- --search-mark-bg: #e69f67;
-}
-
-@media (prefers-color-scheme: dark) {
- .light.no-js {
- --bg: hsl(200, 7%, 8%);
- --fg: #98a3ad;
-
- --sidebar-bg: #292c2f;
- --sidebar-fg: #a1adb8;
- --sidebar-non-existant: #505254;
- --sidebar-active: #3473ad;
- --sidebar-spacer: #393939;
-
- --scrollbar: var(--sidebar-fg);
-
- --icons: #43484d;
- --icons-hover: #b3c0cc;
-
- --links: #2b79a2;
-
- --inline-code-color: #c5c8c6;
-
- --theme-popup-bg: #141617;
- --theme-popup-border: #43484d;
- --theme-hover: #1f2124;
-
- --quote-bg: hsl(234, 21%, 18%);
- --quote-border: hsl(234, 21%, 23%);
-
- --table-border-color: hsl(200, 7%, 13%);
- --table-header-bg: hsl(200, 7%, 28%);
- --table-alternate-bg: hsl(200, 7%, 11%);
-
- --searchbar-border-color: #aaa;
- --searchbar-bg: #b7b7b7;
- --searchbar-fg: #000;
- --searchbar-shadow-color: #aaa;
- --searchresults-header-fg: #666;
- --searchresults-border-color: #98a3ad;
- --searchresults-li-bg: #2b2b2f;
- --search-mark-bg: #355c7d;
- }
-}
diff --git a/docs/nightly/guide/en/custom_renderer/index.html b/docs/nightly/guide/en/custom_renderer/index.html
deleted file mode 100644
index 3005b0003..000000000
--- a/docs/nightly/guide/en/custom_renderer/index.html
+++ /dev/null
@@ -1,823 +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.
--//! Example: README.md showcase -//! -//! The example from the README.md. - -use dioxus::prelude::*; - -fn main() { - dioxus_desktop::launch(app); -} - -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!" } - }) -} -
The rsx! Macro
-Before the Rust compiler runs the program, it will expand all macros. Here is what the hello world example looks like expanded:
--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: Default::default(), - 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), - ]), - } - }, - ), - ) -} -
The rsx macro separates the static parts of the rsx (the template) and the dynamic parts (the dynamic_nodes and dynamic_attributes).
-The static template only contains the parts of the rsx that cannot change at runtime with holes for the dynamic parts:
-
The dynamic_nodes and dynamic_attributes are the parts of the rsx that can change at runtime:
-
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 and create a virtual dom with the root component. This guide will not explain the renderer in-depth, but you can read more about it in the 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.
-The Virtual Dom roughly looks like this:
---#![allow(unused)] -fn main() { -pub struct VirtualDom { - // All the templates that have been created or set durring 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? -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 an node is created in the Virtual Dom, a ElementId is passed along with the mutation to the renderer to identify the node. These ids are used by the Virtual Dom to reference that nodes 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 the 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:
--
-
- They store the state of hooks used by the component -
- They store the state for the context API -
- They store the current and previous VNode that was rendered for diffing -
The Initial Render
-The root scope is created and rebuilt:
--
-
- The root component is run -
- The root component returns a VNode -
- Mutations for the VNode are created and added to the mutation list (this may involve creating new child components) -
- The VNode is stored in the root scope -
After the root scope is built, the mutations are sent to the renderer to be applied to the dom.
-After the initial render, the root scope looks like this:
-
Waiting for Events
-The Virtual Dom will only ever rerender 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.
-There are generally two ways a scope is marked as dirty:
--
-
- The renderer triggers an event: This causes an event listener to be called if needed which may mark a component as dirty -
- The renderer calls wait for work: This polls futures which may mark a component as dirty -
Once at least one scope is marked as dirty, the renderer can call render_with_deadline to diff the dirty scopes.
Diffing Scopes
-If the user clicked the "up high" button, the root scope would be marked as dirty by the use_state hook. Once the desktop renderer calls render_with_deadline, the root scope would be diffed.
To start the diffing process, the component is run. After the root component is run it will look like this:
-
Next, the Virtual Dom will compare the new VNode with the previous VNode and only update the parts of the tree that have changed.
-When a component is re-rendered, the Virtual Dom will compare the new VNode with the previous VNode and only update the parts of the tree that have changed.
-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)
-
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, and how it uses bump allocation to efficiently allocate VNodes. If need more information about the Virtual Dom, you can read the code of the core crate or reach out to us on Discord.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/describing_ui/component_children.html b/docs/nightly/guide/en/describing_ui/component_children.html
deleted file mode 100644
index 497fb766f..000000000
--- a/docs/nightly/guide/en/describing_ui/component_children.html
+++ /dev/null
@@ -1,292 +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:
--
-
- Handle the stream of edits generated by updates to the virtual DOM -
- 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 or tui renderer as a starting point for your custom renderer.
-Templates
-Dioxus is built around the concept of Templates. 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:
--#![allow(unused)] -fn main() { -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 where the LoadTemplate, CreatePlaceholder, and CreateTextNode mutations pushes a new "real" DOM node onto the stack and AppendChildren, InsertAfter, InsertBefore, ReplacePlaceholder, and 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
An Example
-For the sake of understanding, let's consider this example – a very simple UI declaration:
---#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -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
-
This template will be sent to the renderer in the list of templates supplied with the mutations the first time it is used. Any time the renderer encounters a 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:
-<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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -[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:
-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.
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.
Native Core
-If you are creating a renderer in rust, the 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:
---#![allow(unused)] -fn main() { -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:
-
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:
// 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
-}
-Lets take a look at how to implement the State trait for a simple renderer.
---#![allow(unused)] -fn main() { -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 - } -} -} -
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.
--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:?}"); - }); - } - }) -} -
Layout
-For most platforms, the layout of the Elements will stay the same. The layout_attributes module provides a way to apply HTML attributes a Taffy 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.
--#![allow(unused)] -fn main() { -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); -} -} -
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.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/describing_ui/component_props.html b/docs/nightly/guide/en/describing_ui/component_props.html
deleted file mode 100644
index 29414b577..000000000
--- a/docs/nightly/guide/en/describing_ui/component_props.html
+++ /dev/null
@@ -1,466 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- The
-
-
-
-
- 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:
--#![allow(unused)] -fn main() { -#[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 - } - )) -} -} -
Then, when rendering the component, you can pass in the output of cx.render(rsx!(...)):
--#![allow(unused)] -fn main() { - cx.render(rsx! { - Clickable { - href: "https://www.youtube.com/watch?v=C-M2hs3sXGo", - body: cx.render(rsx!("How to " i {"not"} " be seen")), - } - }) -} -
--Note: Since
-Element<'a>is a borrowed prop, there will be no memoization.
--Warning: While it may compile, do not include the same
-Elementmore 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:
--#![allow(unused)] -fn main() { -#[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 - } - )) -} -} -
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!
- --#![allow(unused)] -fn main() { - cx.render(rsx! { - Clickable { - href: "https://www.youtube.com/watch?v=C-M2hs3sXGo", - "How to " i {"not"} " be seen" - } - }) -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/describing_ui/components.html b/docs/nightly/guide/en/describing_ui/components.html
deleted file mode 100644
index d5eb911f1..000000000
--- a/docs/nightly/guide/en/describing_ui/components.html
+++ /dev/null
@@ -1,265 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Explicitly Required
-Automatic Conversion with
-The
-
-
-
-
- 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 from a parent component -
- Cannot be memoized due to lifetime constraints -
-
Owned Props
-Owned Props are very simple – they don't borrow anything. Example:
---#![allow(unused)] -fn main() { -// 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" - } - }) -} -} -
You can then pass prop values to the component the same way you would pass attributes to an element:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - cx.render(rsx! { - Likes { - score: 42, - }, - }) -} -} -
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() 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!
--#![allow(unused)] -fn main() { -#[derive(Props)] -struct TitleCardProps<'a> { - title: &'a str, -} - -fn TitleCard<'a>(cx: Scope<'a, TitleCardProps<'a>>) -> Element { - cx.render(rsx! { - h1 { "{cx.props.title}" } - }) -} -} -
We can then use the component like this:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - let hello = "Hello Dioxus!"; - - cx.render(rsx!(TitleCard { title: hello })) -} -} -
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:
--#![allow(unused)] -fn main() { -#[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"), - })) -} -} -
Then, you can choose to either provide them or not:
---#![allow(unused)] -fn main() { -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, -// }, -} -
Explicitly Required Options
-If you want to explicitly require an Option, and not an optional prop, you can annotate it with #[props(!optional)]:
--#![allow(unused)] -fn main() { -#[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"), - })) -} -} -
Then, you have to explicitly pass either Some("str") or None:
--#![allow(unused)] -fn main() { -ExplicitOption { - title: "Some Title", - subtitle: None, -}, -ExplicitOption { - title: "Some Title", - subtitle: Some("Some Title"), -}, -// This won't compile: -// ExplicitOption { -// title: "Some Title", -// }, -} -
Default Props
-You can use #[props(default = 42)] to make a field optional and specify its default value:
--#![allow(unused)] -fn main() { -#[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}" })) -} -} -
Then, similarly to optional props, you don't have to provide it:
---#![allow(unused)] -fn main() { -DefaultComponent { - number: 5, -}, -DefaultComponent {}, -} -
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:
--#![allow(unused)] -fn main() { -#[derive(PartialEq, Props)] -struct IntoProps { - #[props(into)] - string: String, -} - -fn IntoComponent(cx: Scope<IntoProps>) -> Element { - cx.render(rsx!(h1 { "{cx.props.string}" })) -} -} -
Then, you can use it so:
---#![allow(unused)] -fn main() { -IntoComponent { - string: "some &str", -}, -} -
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:
--#![allow(unused)] -fn main() { -#[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:
--#![allow(unused)] -fn main() { -#[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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/describing_ui/images/component_borrowed_props_screenshot.png b/docs/nightly/guide/en/describing_ui/images/component_borrowed_props_screenshot.png
deleted file mode 100644
index 6f1864662..000000000
Binary files a/docs/nightly/guide/en/describing_ui/images/component_borrowed_props_screenshot.png and /dev/null differ
diff --git a/docs/nightly/guide/en/describing_ui/images/component_owned_props_screenshot.png b/docs/nightly/guide/en/describing_ui/images/component_owned_props_screenshot.png
deleted file mode 100644
index 2a1146cd1..000000000
Binary files a/docs/nightly/guide/en/describing_ui/images/component_owned_props_screenshot.png and /dev/null differ
diff --git a/docs/nightly/guide/en/describing_ui/images/screenshot_about_component.png b/docs/nightly/guide/en/describing_ui/images/screenshot_about_component.png
deleted file mode 100644
index 36f7250a1..000000000
Binary files a/docs/nightly/guide/en/describing_ui/images/screenshot_about_component.png and /dev/null differ
diff --git a/docs/nightly/guide/en/describing_ui/index.html b/docs/nightly/guide/en/describing_ui/index.html
deleted file mode 100644
index f63ed5fad..000000000
--- a/docs/nightly/guide/en/describing_ui/index.html
+++ /dev/null
@@ -1,404 +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!
--#![allow(unused)] -fn main() { -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
--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:
--#![allow(unused)] -fn main() { -pub fn About(cx: Scope) -> Element { - cx.render(rsx!(p { - b {"Dioxus Labs"} - " An Open Source project dedicated to making Rust UI wonderful." - })) -} -} -
Then, you can render your component in another component, similarly to how elements are rendered:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - cx.render(rsx! { - About {}, - About {}, - }) -} -} -
-- -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!
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/describing_ui/special_attributes.html b/docs/nightly/guide/en/describing_ui/special_attributes.html
deleted file mode 100644
index 1cb196b66..000000000
--- a/docs/nightly/guide/en/describing_ui/special_attributes.html
+++ /dev/null
@@ -1,286 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Describing the UI
-Dioxus is a declarative framework. This means that instead of telling Dioxus what to do (e.g. to "create an element" or "set the color to red") we simply declare what we want the UI to look like using RSX.
-You have already seen a simple example of RSX syntax in the "hello world" application:
---#![allow(unused)] -fn main() { -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
Here, we use the rsx! macro to declare that we want a div element, containing the text "Hello, world!". Dioxus takes the RSX and constructs a UI from it.
RSX Features
-RSX is very similar to HTML in that it describes elements with attributes and children. Here's an empty div element in RSX, as well as the resulting HTML:
--#![allow(unused)] -fn main() { -cx.render(rsx!(div { - // attributes / listeners - // children -})) -} -
<div></div>
-Attributes
-Attributes (and listeners) modify the behavior or appearance of the element they are attached to. They are specified inside the {} brackets, using the name: value syntax. You can provide the value as a literal in the RSX:
--#![allow(unused)] -fn main() { -cx.render(rsx!(a { - href: "https://www.youtube.com/watch?v=dQw4w9WgXcQ", - class: "primary_button", - color: "red", -})) -} -
<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" class="primary_button" autofocus="true" style="color: red"></a>
---Note: All attributes defined in
-dioxus-htmlfollow the snake_case naming convention. They transform theirsnake_casenames to HTML'scamelCaseattributes.
--Note: Styles can be used directly outside of the
-style:attribute. In the above example,color: "red"is turned intostyle="color: red".
Custom Attributes
-Dioxus has a pre-configured set of attributes that you can use. RSX is validated at compile time to make sure you didn't specify an invalid attribute. If you want to override this behavior with a custom attribute name, specify the attribute in quotes:
---#![allow(unused)] -fn main() { - cx.render(rsx!(b { - "customAttribute": "value", - })) -} -
<b customAttribute="value">
-</b>
-Interpolation
-Similarly to how you can format Rust strings, you can also interpolate in RSX text. Use {variable} to Display the value of a variable in a string, or {variable:?} to use the Debug representation:
--#![allow(unused)] -fn main() { -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 { - "{{}}" - }, -})) -} -
<div class="country-es" position="(42, 0)">
- <div>ES</div>
- <div>42</div>
- <div>{}</div>
-</div>
-Children
-To add children to an element, put them inside the {} brackets after all attributes and listeners in the element. They can be other elements, text, or components. For example, you could have an ol (ordered list) element, containing 3 li (list item) elements, each of which contains some text:
--#![allow(unused)] -fn main() { -cx.render(rsx!(ol { - li {"First Item"} - li {"Second Item"} - li {"Third Item"} -})) -} -
<ol>
- <li>First Item</li>
- <li>Second Item</li>
- <li>Third Item</li>
-</ol>
-Fragments
-You can render multiple elements at the top level of rsx! and they will be automatically grouped.
--#![allow(unused)] -fn main() { -cx.render(rsx!( - p {"First Item"}, - p {"Second Item"}, -)) -} -
<p>First Item</p>
-<p>Second Item</p>
-Expressions
-You can include arbitrary Rust expressions as children within RSX that implements IntoDynNode. This is useful for displaying data from an iterator:
---#![allow(unused)] -fn main() { -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() }) -})) -} -
<span>DIOXUS0123456789</span>
-Loops
-In addition to iterators you can also use for loops directly within RSX:
---#![allow(unused)] -fn main() { -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}" } }) - } -}) -} -
<div>0</div>
-<div>1</div>
-<div>2</div>
-<div>0</div>
-<div>1</div>
-<div>2</div>
-If statements
-You can also use if statements without an else branch within RSX:
---#![allow(unused)] -fn main() { -cx.render(rsx!{ - // use if statements without an else - if true { - rsx!(div { "true" }) - } -}) -} -
<div>true</div>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/editor.js b/docs/nightly/guide/en/editor.js
deleted file mode 100644
index 464790c49..000000000
--- a/docs/nightly/guide/en/editor.js
+++ /dev/null
@@ -1,29 +0,0 @@
-"use strict";
-window.editors = [];
-(function(editors) {
- if (typeof(ace) === 'undefined' || !ace) {
- return;
- }
-
- Array.from(document.querySelectorAll('.editable')).forEach(function(editable) {
- let display_line_numbers = window.playground_line_numbers || false;
-
- let editor = ace.edit(editable);
- editor.setOptions({
- highlightActiveLine: false,
- showPrintMargin: false,
- showLineNumbers: display_line_numbers,
- showGutter: display_line_numbers,
- maxLines: Infinity,
- fontSize: "0.875em" // please adjust the font size of the code in general.css
- });
-
- editor.$blockScrolling = Infinity;
-
- editor.getSession().setMode("ace/mode/rust");
-
- editor.originalCode = editor.getValue();
-
- editors.push(editor);
- });
-})(window.editors);
diff --git a/docs/nightly/guide/en/elasticlunr.min.js b/docs/nightly/guide/en/elasticlunr.min.js
deleted file mode 100644
index 94b20dd2e..000000000
--- a/docs/nightly/guide/en/elasticlunr.min.js
+++ /dev/null
@@ -1,10 +0,0 @@
-/**
- * elasticlunr - http://weixsong.github.io
- * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5
- *
- * Copyright (C) 2017 Oliver Nightingale
- * Copyright (C) 2017 Wei Song
- * MIT Licensed
- * @license
- */
-!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Special Attributes
-While most attributes are simply passed on to the HTML, some have special behaviors.
-The HTML Escape Hatch
-If you're working with pre-rendered assets, output from templates, or output from a JS library, then you might want to pass HTML directly instead of going through Dioxus. In these instances, reach for dangerous_inner_html.
For example, shipping a markdown-to-Dioxus converter might significantly bloat your final application size. Instead, you'll want to pre-render your markdown to HTML and then include the HTML directly in your output. We use this approach for the Dioxus homepage:
---#![allow(unused)] -fn main() { -// this should come from a trusted source -let contents = "live <b>dangerously</b>"; - -cx.render(rsx! { - div { - dangerous_inner_html: "{contents}", - } -}) -} -
--Note! This attribute is called "dangerous_inner_html" because it is dangerous to pass it data you don't trust. If you're not careful, you can easily expose cross-site scripting (XSS) attacks to your users.
-If you're handling untrusted input, make sure to sanitize your HTML before passing it into
-dangerous_inner_html– or just pass it to a Text Element to escape any HTML tags.
Boolean Attributes
-Most attributes, when rendered, will be rendered exactly as the input you provided. However, some attributes are considered "boolean" attributes and just their presence determines whether they affect the output. For these attributes, a provided value of "false" will cause them to be removed from the target element.
So this RSX wouldn't actually render the hidden attribute:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - div { - hidden: "false", - "hello" - } -}) -} -
<div>hello</div>
-Not all attributes work like this however. Only the following attributes have this behavior:
--
-
allowfullscreen
-allowpaymentrequest
-async
-autofocus
-autoplay
-checked
-controls
-default
-defer
-disabled
-formnovalidate
-hidden
-ismap
-itemscope
-loop
-multiple
-muted
-nomodule
-novalidate
-open
-playsinline
-readonly
-required
-reversed
-selected
-truespeed
-
For any other attributes, a value of "false" will be sent directly to the DOM.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/fullstack/index.html b/docs/nightly/guide/en/fullstack/index.html
deleted file mode 100644
index 43d5aae67..000000000
--- a/docs/nightly/guide/en/fullstack/index.html
+++ /dev/null
@@ -1,285 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- --This guide assumes you read the Web guide and installed the Dioxus-cli
-
Getting Started
-Setup
-For this guide, we're going to show how to use Dioxus with Axum, but dioxus-fullstack also integrates with the Warp and Salvo web frameworks.
Make sure you have Rust and Cargo installed, and then create a new project:
-cargo new --bin demo
-cd demo
-Add dioxus and dioxus-fullstack as dependencies:
cargo add dioxus
-cargo add dioxus-fullstack --features axum, ssr
-Next, add all the Axum dependencies. This will be different if you're using a different Web Framework
-cargo add tokio --features full
-cargo add axum
-Your dependencies should look roughly like this:
-[dependencies]
-axum = "*"
-dioxus = { version = "*" }
-dioxus-fullstack = { version = "*", features = ["axum", "ssr"] }
-tokio = { version = "*", features = ["full"] }
-Now, set up your Axum app to serve the Dioxus app.
--#![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!" } - }) -} -
Now, run your app with cargo run and open http://localhost:8080 in your browser. You should see a server-side rendered page with a counter.
Hydration
-Right now, the page is static. We can't interact with the buttons. To fix this, we can hydrate the page with dioxus-web.
First, modify your Cargo.toml to include two features, one for the server called ssr, and one for the client called web.
[dependencies]
-# Common dependancies
-dioxus = { version = "*" }
-dioxus-fullstack = { version = "*" }
-
-# Web dependancies
-dioxus-web = { version = "*", features=["hydrate"], optional = true }
-
-# Server dependancies
-axum = { version = "0.6.12", optional = true }
-tokio = { version = "1.27.0", features = ["full"], optional = true }
-
-[features]
-default = []
-ssr = ["axum", "tokio", "dioxus-fullstack/axum"]
-web = ["dioxus-web"]
-Next, we need to modify our main.rs to use either hydrate on the client or render on the server depending on the active features.
-#![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!" } - }) -} -
Now, build your client-side bundle with dioxus build --features web and run your server with cargo run --features ssr. You should see the same page as before, but now you can interact with the buttons!
Sycronizing props between the server and client
-Let's make the initial count of the counter dynamic based on the current page.
-Modifying the server
-To do this, we must remove the serve_dioxus_application and replace it with a custom implementation of its four key functions:
--
-
- Serve static WASM and JS files with serve_static_assets -
- Register server functions with register_server_fns (more information on server functions later) -
- Connect to the hot reload server with connect_hot_reload -
- A custom route that uses SSRState to server-side render the application -
Modifying the client
-The only thing we need to change on the client is the props. dioxus-fullstack will automatically serialize the props it uses to server render the app and send them to the client. In the client section of main.rs, we need to add get_root_props_from_document to deserialize the props before we hydrate the app.
-#![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!" } - }) -} -
Now, build your client-side bundle with dioxus build --features web and run your server with cargo run --features ssr. Navigate to http://localhost:8080/1 and you should see the counter start at 1. Navigate to http://localhost:8080/2 and you should see the counter start at 2.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/fullstack/server_functions.html b/docs/nightly/guide/en/fullstack/server_functions.html
deleted file mode 100644
index 1fc80efa3..000000000
--- a/docs/nightly/guide/en/fullstack/server_functions.html
+++ /dev/null
@@ -1,335 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Fullstack development
-So far you have learned about three different approaches to target the web with Dioxus:
--
-
- Client-side rendering with dioxus-web -
- Server-side rendering with dioxus-liveview -
- Server-side static HTML generation with dioxus-ssr -
Summary of Existing Approaches
-Each approach has its tradeoffs:
-Client-side rendering
--
-
-
-
With Client side rendering, you send the entire content of your application to the client, and then the client generates all of the HTML of the page dynamically.
-
- -
-
This means that the page will be blank until the JavaScript bundle has loaded and the application has initialized. This can result in slower first render times and makes the page less SEO-friendly.
-
-
--SEO stands for Search Engine Optimization. It refers to the practice of making your website more likely to appear in search engine results. Search engines like Google and Bing use web crawlers to index the content of websites. Most of these crawlers are not able to run JavaScript, so they will not be able to index the content of your page if it is rendered client-side.
-
-
-
- Client-side rendered applications need to use weakly typed requests to communicate with the server -
--Client-side rendering is a good starting point for most applications. It is well supported and makes it easy to communicate with the client/browser APIs
-
Liveview
--
-
-
-
Liveview rendering communicates with the server over a WebSocket connection. It essentially moves all of the work that Client-side rendering does to the server.
-
- -
-
This makes it easy to communicate with the server, but more difficult to communicate with the client/browser APIS.
-
- -
-
Each interaction also requires a message to be sent to the server and back which can cause issues with latency.
-
- -
-
Because Liveview uses a websocket to render, the page will be blank until the WebSocket connection has been established and the first renderer has been sent form the websocket. Just like with client side rendering, this can make the page less SEO-friendly.
-
- -
-
Because the page is rendered on the server and the page is sent to the client piece by piece, you never need to send the entire application to the client. The initial load time can be faster than client-side rendering with large applications because Liveview only needs to send a constant small websocket script regardless of the size of the application.
-
-
--Liveview is a good fit for applications that already need to communicate with the server frequently (like real time collaborative apps), but don't need to communicate with as many client/browser APIs
-
Server-side rendering
--
-
- Server-side rendering generates all of the HTML of the page on the server before the page is sent to the client. This means that the page will be fully rendered when it is sent to the client. This results in a faster first render time and makes the page more SEO-friendly. However, it only works for static pages. -
--Server-side rendering is not a good fit for purely static sites like a blog
-
A New Approach
-Each of these approaches has its tradeoffs. What if we could combine the best parts of each approach?
--
-
- Fast initial render time like SSR -
- Works well with SEO like SSR -
- Type safe easy communication with the server like Liveview -
- Access to the client/browser APIs like Client-side rendering -
- Fast interactivity like Client-side rendering -
We can achieve this by rendering the initial page on the server (SSR) and then taking over rendering on the client (Client-side rendering). Taking over rendering on the client is called hydration.
-Finally, we can use server functions to communicate with the server in a type-safe way.
-This approach uses both the dioxus-web and dioxus-ssr crates. To integrate those two packages and axum, warp, or salvo, Dioxus provides the dioxus-fullstack crate.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/desktop.html b/docs/nightly/guide/en/getting_started/desktop.html
deleted file mode 100644
index d91cefcf3..000000000
--- a/docs/nightly/guide/en/getting_started/desktop.html
+++ /dev/null
@@ -1,280 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Communicating with the server
-dixous-server provides server functions that allow you to call an automatically generated API on the server from the client as if it were a local function.
To make a server function, simply add the #[server(YourUniqueType)] attribute to a function. The function must:
-
-
- Be an async function -
- Have arguments and a return type that both implement serialize and deserialize (with serde). -
- Return a
Resultwith an error type of ServerFnError
-
You must call register on the type you passed into the server macro in your main function before starting your server to tell Dioxus about the server function.
Let's continue building on the app we made in the getting started guide. We will add a server function to our app that allows us to double the count on the server.
-First, add serde as a dependency:
-cargo add serde
-Next, add the server function to your main.rs:
-#![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; - - // Register the server function before starting the server - DoubleServer::register().unwrap(); - - 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) -} -
Now, build your client-side bundle with dioxus build --features web and run your server with cargo run --features ssr. You should see a new button that multiplies the count by 2.
Conclusion
-That's it! You've created a full-stack Dioxus app. You can find more examples of full-stack apps and information about how to integrate with other frameworks and desktop renderers in the dioxus-fullstack examples directory.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/fullstack.html b/docs/nightly/guide/en/getting_started/fullstack.html
deleted file mode 100644
index aa24b8a71..000000000
--- a/docs/nightly/guide/en/getting_started/fullstack.html
+++ /dev/null
@@ -1,219 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Desktop Overview
-Build a standalone native desktop app that looks and feels the same across operating systems.
-Apps built with Dioxus are typically <5mb in size and use existing system resources, so they won't hog extreme amounts of RAM or memory.
-Examples:
- -
Support
-The desktop is a powerful target for Dioxus but is currently limited in capability when compared to the Web platform. Currently, desktop apps are rendered with the platform's WebView library, but your Rust code is running natively on a native thread. This means that browser APIs are not available, so rendering WebGL, Canvas, etc is not as easy as the Web. However, native system APIs are accessible, so streaming, WebSockets, filesystem, etc are all viable APIs. In the future, we plan to move to a custom web renderer-based DOM renderer with WGPU integrations.
-Dioxus Desktop is built off Tauri. Right now there aren't any Dioxus abstractions over the menubar, handling, etc, so you'll want to leverage Tauri – mostly Wry and Tao) directly.
-Getting started
-Platform-Specific Dependencies
-Dioxus desktop renders through a web view. Depending on your platform, you might need to install some dependancies.
-Windows
-Windows Desktop apps depend on WebView2 – a library that should be installed in all modern Windows distributions. If you have Edge installed, then Dioxus will work fine. If you don't have Webview2, then you can install it through Microsoft. MS provides 3 options:
--
-
- A tiny "evergreen" bootstrapper that fetches an installer from Microsoft's CDN -
- A tiny installer that fetches Webview2 from Microsoft's CDN -
- A statically linked version of Webview2 in your final binary for offline users -
For development purposes, use Option 1.
-Linux
-Webview Linux apps require WebkitGtk. When distributing, this can be part of your dependency tree in your .rpm or .deb. However, likely, your users will already have WebkitGtk.
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev
-When using Debian/bullseye libappindicator3-dev is no longer available but replaced by libayatana-appindicator3-dev.
# on Debian/bullseye use:
-sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev
-If you run into issues, make sure you have all the basics installed, as outlined in the Tauri docs.
-MacOS
-Currently – everything for macOS is built right in! However, you might run into an issue if you're using nightly Rust due to some permissions issues in our Tao dependency (which have been resolved but not published).
-Creating a Project
-Create a new crate:
-cargo new --bin demo
-cd demo
-Add Dioxus and the desktop renderer as dependencies (this will edit your Cargo.toml):
cargo add dioxus
-cargo add dioxus-desktop
-Edit your main.rs:
- -#![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); -} - -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/hot_reload.html b/docs/nightly/guide/en/getting_started/hot_reload.html
deleted file mode 100644
index c083eddcd..000000000
--- a/docs/nightly/guide/en/getting_started/hot_reload.html
+++ /dev/null
@@ -1,266 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Fullstack
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/index.html b/docs/nightly/guide/en/getting_started/index.html
deleted file mode 100644
index f5f1eb4b8..000000000
--- a/docs/nightly/guide/en/getting_started/index.html
+++ /dev/null
@@ -1,243 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Setting Up Hot Reload
--
-
- Hot reloading allows much faster iteration times inside of rsx calls by interpreting them and streaming the edits. -
- It is useful when changing the styling/layout of a program, but will not help with changing the logic of a program. -
- Currently the cli only implements hot reloading for the web renderer. For TUI, desktop, and LiveView you can use the hot reload macro instead. -
Web
-For the web renderer, you can use the dioxus cli to serve your application with hot reloading enabled.
-Setup
-Install dioxus-cli. -Hot reloading is automatically enabled when using the web renderer on debug builds.
-Usage
--
-
- Run: -
dioxus serve --hot-reload
--
-
- Change some code within a rsx or render macro -
- Open your localhost in a browser -
- Save and watch the style change without recompiling -
Desktop/Liveview/TUI/Server
-For desktop, LiveView, and tui, you can place the hot reload macro at the top of your main function to enable hot reloading. -Hot reloading is automatically enabled on debug builds.
-For more information about hot reloading on native platforms and configuration options see the dioxus-hot-reload crate.
-Setup
-Add the following to your main function:
--fn main() { - hot_reload_init!(); - // launch your application -} -
Usage
--
-
- Run: -
cargo run
--
-
- Change some code within a rsx or render macro -
- Save and watch the style change without recompiling -
Limitations
--
-
- The interpreter can only use expressions that existed on the last full recompile. If you introduce a new variable or expression to the rsx call, it will require a full recompile to capture the expression. -
- Components, Iterators, and some attributes can contain arbitrary rust code and will trigger a full recompile when changed. -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/liveview.html b/docs/nightly/guide/en/getting_started/liveview.html
deleted file mode 100644
index 89d34f670..000000000
--- a/docs/nightly/guide/en/getting_started/liveview.html
+++ /dev/null
@@ -1,308 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Getting Started
-This section will help you set up your Dioxus project!
-Prerequisites
-An Editor
-Dioxus integrates very well with the Rust-Analyzer LSP plugin which will provide appropriate syntax highlighting, code navigation, folding, and more.
-Rust
-Head over to https://rust-lang.org and install the Rust compiler.
-We strongly recommend going through the official Rust book completely. However, we hope that a Dioxus app can serve as a great first Rust project. With Dioxus, you'll learn about:
--
-
- Error handling -
- Structs, Functions, Enums -
- Closures -
- Macros -
We've put a lot of care into making Dioxus syntax familiar and easy to understand, so you won't need deep knowledge of async, lifetimes, or smart pointers until you start building complex Dioxus apps.
-Setup Guides
-Dioxus supports multiple platforms. Choose the platform you want to target below to get platform-specific setup instructions:
--
-
- Web: runs in the browser through WebAssembly -
- Server Side Rendering: renders to HTML text on the server -
- Liveview: runs on the server, renders in the browser using WebSockets -
- Desktop: runs in a web view on desktop -
- Mobile: runs in a web view on mobile -
- Terminal UI: renders text-based graphics in the terminal -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/mobile.html b/docs/nightly/guide/en/getting_started/mobile.html
deleted file mode 100644
index f9fe2e9ab..000000000
--- a/docs/nightly/guide/en/getting_started/mobile.html
+++ /dev/null
@@ -1,274 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Liveview
-Liveview allows apps to run on the server and render in the browser. It uses WebSockets to communicate between the server and the browser.
-Examples:
- -Support
-Liveview is currently limited in capability when compared to the Web platform. Liveview apps run on the server in a native thread. This means that browser APIs are not available, so rendering WebGL, Canvas, etc is not as easy as the Web. However, native system APIs are accessible, so streaming, WebSockets, filesystem, etc are all viable APIs.
-Setup
-For this guide, we're going to show how to use Dioxus Liveview with Axum.
-Make sure you have Rust and Cargo installed, and then create a new project:
-cargo new --bin demo
-cd app
-Add Dioxus and the liveview renderer with the Axum feature as dependencies:
-cargo add dioxus
-cargo add dioxus-liveview --features axum
-Next, add all the Axum dependencies. This will be different if you're using a different Web Framework
-cargo add tokio --features full
-cargo add axum
-Your dependencies should look roughly like this:
-[dependencies]
-axum = "0.4.5"
-dioxus = { version = "*" }
-dioxus-liveview = { version = "*", features = ["axum"] }
-tokio = { version = "1.15.0", features = ["full"] }
-Now, set up your Axum app to respond on an endpoint.
--#[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(); -} -
And then add our app component:
---#![allow(unused)] -fn main() { -fn app(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
And that's it!
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/ssr.html b/docs/nightly/guide/en/getting_started/ssr.html
deleted file mode 100644
index 20b485bd5..000000000
--- a/docs/nightly/guide/en/getting_started/ssr.html
+++ /dev/null
@@ -1,313 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Mobile App
-Build a mobile app with Dioxus!
-Example: Todo App
-Support
-Mobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with either the platform's WebView or experimentally through WGPU. WebView doesn't support animations, transparency, and native widgets.
-Mobile support is currently best suited for CRUD-style apps, ideally for internal teams who need to develop quickly but don't care much about animations or native widgets.
-This guide is primarily targeted at iOS apps, however, you can follow it while using the android guide in cargo-mobile.
Getting Set up
-Getting set up with mobile can be quite challenging. The tooling here isn't great (yet) and might take some hacking around to get things working. macOS M1 is broadly unexplored and might not work for you.
-We're going to be using cargo-mobile to build for mobile. First, install it:
cargo install --git https://github.com/BrainiumLLC/cargo-mobile
-And then initialize your app for the right platform. Use the winit template for now. Right now, there's no "Dioxus" template in cargo-mobile.
cargo mobile init
-We're going to completely clear out the dependencies it generates for us, swapping out winit with dioxus-mobile.
-[package]
-name = "dioxus-ios-demo"
-version = "0.1.0"
-authors = []
-edition = "2018"
-
-
-# leave the `lib` declaration
-[lib]
-crate-type = ["staticlib", "cdylib", "rlib"]
-
-
-# leave the binary it generates for us
-[[bin]]
-name = "dioxus-ios-demo-desktop"
-path = "gen/bin/desktop.rs"
-
-# clear all the dependencies
-[dependencies]
-mobile-entry-point = "0.1.0"
-dioxus = { version = "*"}
-dioxus-desktop = { version = "*" }
-simple_logger = "*"
-Edit your lib.rs:
- -use dioxus::prelude::*; - -fn main() { - dioxus_desktop::launch(app); -} - -fn app(cx: Scope) -> Element { - cx.render(rsx!{ - div { - "hello world!" - } - }) -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/tui.html b/docs/nightly/guide/en/getting_started/tui.html
deleted file mode 100644
index 287ed8ed6..000000000
--- a/docs/nightly/guide/en/getting_started/tui.html
+++ /dev/null
@@ -1,300 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Server-Side Rendering
-For lower-level control over the rendering process, you can use the dioxus-ssr crate directly. This can be useful when integrating with a web framework that dioxus-server does not support, or pre-rendering pages.
Setup
-For this guide, we're going to show how to use Dioxus SSR with Axum.
-Make sure you have Rust and Cargo installed, and then create a new project:
-cargo new --bin demo
-cd demo
-Add Dioxus and the ssr renderer as dependencies:
-cargo add dioxus
-cargo add dioxus-ssr
-Next, add all the Axum dependencies. This will be different if you're using a different Web Framework
-cargo add tokio --features full
-cargo add axum
-Your dependencies should look roughly like this:
-[dependencies]
-axum = "0.4.5"
-dioxus = { version = "*" }
-dioxus-ssr = { version = "*" }
-tokio = { version = "1.15.0", features = ["full"] }
-Now, set up your Axum app to respond on an endpoint.
--#![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(); -} - -
And then add our endpoint. We can either render rsx! directly:
--#![allow(unused)] -fn main() { -async fn app_endpoint() -> Html<String> { - // render the rsx! macro to HTML - Html(dioxus_ssr::render_lazy(rsx! { - div { "hello world!" } - })) -} -} -
Or we can render VirtualDoms.
---#![allow(unused)] -fn main() { -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)) -} -} -
And then add our app component:
---#![allow(unused)] -fn main() { -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
And that's it!
-Multithreaded Support
-The Dioxus VirtualDom, sadly, is not currently Send. Internally, we use quite a bit of interior mutability which is not thread-safe.
-When working with web frameworks that require Send, it is possible to render a VirtualDom immediately to a String – but you cannot hold the VirtualDom across an await point. For retained-state SSR (essentially LiveView), you'll need to spawn a VirtualDom on its own thread and communicate with it via channels or create a pool of VirtualDoms.
-You might notice that you cannot hold the VirtualDom across an await point. Because Dioxus is currently not ThreadSafe, it must remain on the thread it started. We are working on loosening this requirement.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/getting_started/web.html b/docs/nightly/guide/en/getting_started/web.html
deleted file mode 100644
index 69fd8bbef..000000000
--- a/docs/nightly/guide/en/getting_started/web.html
+++ /dev/null
@@ -1,274 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Terminal UI
-You can build a text-based interface that will run in the terminal using Dioxus.
-
--Note: this book was written with HTML-based platforms in mind. You might be able to follow along with TUI, but you'll have to adapt a bit.
-
Support
-TUI support is currently quite experimental. But, if you're willing to venture into the realm of the unknown, this guide will get you started.
--
-
- It uses flexbox for the layout -
- It only supports a subset of the attributes and elements -
- Regular widgets will not work in the tui render, but the tui renderer has its own widget components that start with a capital letter. See the widgets example -
- 1px is one character line height. Your regular CSS px does not translate -
- If your app panics, your terminal is wrecked. This will be fixed eventually -
Getting Set up
-Start by making a new package and adding Dioxus and the TUI renderer as dependancies.
-cargo new --bin demo
-cd demo
-cargo add dioxus
-cargo add dioxus-tui
-Then, edit your main.rs with the basic template.
-#![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!" - } - }) -} -
To run our app:
-cargo run
-Press "ctrl-c" to close the app. To switch from "ctrl-c" to just "q" to quit you can launch the app with a configuration to disable the default quit and use the root TuiContext to quit on your own.
-- -// 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!" - } - }) -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/highlight.css b/docs/nightly/guide/en/highlight.css
deleted file mode 100644
index c23432272..000000000
--- a/docs/nightly/guide/en/highlight.css
+++ /dev/null
@@ -1,83 +0,0 @@
-/*
- * An increased contrast highlighting scheme loosely based on the
- * "Base16 Atelier Dune Light" theme by Bram de Haan
- * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
- * Original Base16 color scheme by Chris Kempson
- * (https://github.com/chriskempson/base16)
- */
-
-/* Comment */
-.hljs-comment,
-.hljs-quote {
- color: #575757;
-}
-
-/* Red */
-.hljs-variable,
-.hljs-template-variable,
-.hljs-attribute,
-.hljs-tag,
-.hljs-name,
-.hljs-regexp,
-.hljs-link,
-.hljs-name,
-.hljs-selector-id,
-.hljs-selector-class {
- color: #d70025;
-}
-
-/* Orange */
-.hljs-number,
-.hljs-meta,
-.hljs-built_in,
-.hljs-builtin-name,
-.hljs-literal,
-.hljs-type,
-.hljs-params {
- color: #b21e00;
-}
-
-/* Green */
-.hljs-string,
-.hljs-symbol,
-.hljs-bullet {
- color: #008200;
-}
-
-/* Blue */
-.hljs-title,
-.hljs-section {
- color: #0030f2;
-}
-
-/* Purple */
-.hljs-keyword,
-.hljs-selector-tag {
- color: #9d00ec;
-}
-
-.hljs {
- display: block;
- overflow-x: auto;
- background: #f6f7f6;
- color: #000;
- padding: 0.5em;
-}
-
-.hljs-emphasis {
- font-style: italic;
-}
-
-.hljs-strong {
- font-weight: bold;
-}
-
-.hljs-addition {
- color: #22863a;
- background-color: #f0fff4;
-}
-
-.hljs-deletion {
- color: #b31d28;
- background-color: #ffeef0;
-}
diff --git a/docs/nightly/guide/en/highlight.js b/docs/nightly/guide/en/highlight.js
deleted file mode 100644
index 180385b70..000000000
--- a/docs/nightly/guide/en/highlight.js
+++ /dev/null
@@ -1,6 +0,0 @@
-/*
- Highlight.js 10.1.1 (93fd0d73)
- License: BSD-3-Clause
- Copyright (c) 2006-2020, Ivan Sagalaev
-*/
-var hljs=function(){"use strict";function e(n){Object.freeze(n);var t="function"==typeof n;return Object.getOwnPropertyNames(n).forEach((function(r){!Object.hasOwnProperty.call(n,r)||null===n[r]||"object"!=typeof n[r]&&"function"!=typeof n[r]||t&&("caller"===r||"callee"===r||"arguments"===r)||Object.isFrozen(n[r])||e(n[r])})),n}class n{constructor(e){void 0===e.data&&(e.data={}),this.data=e.data}ignoreMatch(){this.ignore=!0}}function t(e){return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'")}function r(e,...n){var t={};for(const n in e)t[n]=e[n];return n.forEach((function(e){for(const n in e)t[n]=e[n]})),t}function a(e){return e.nodeName.toLowerCase()}var i=Object.freeze({__proto__:null,escapeHTML:t,inherit:r,nodeStream:function(e){var n=[];return function e(t,r){for(var i=t.firstChild;i;i=i.nextSibling)3===i.nodeType?r+=i.nodeValue.length:1===i.nodeType&&(n.push({event:"start",offset:r,node:i}),r=e(i,r),a(i).match(/br|hr|img|input/)||n.push({event:"stop",offset:r,node:i}));return r}(e,0),n},mergeStreams:function(e,n,r){var i=0,s="",o=[];function l(){return e.length&&n.length?e[0].offset!==n[0].offset?e[0].offset
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Web
-Build single-page applications that run in the browser with Dioxus. To run on the Web, your app must be compiled to WebAssembly and depend on the dioxus and dioxus-web crates.
A build of Dioxus for the web will be roughly equivalent to the size of a React build (70kb vs 65kb) but it will load significantly faster because WebAssembly can be compiled as it is streamed.
-Examples:
- -
--Note: Because of the limitations of Wasm, not every crate will work with your web apps, so you'll need to make sure that your crates work without native system calls (timers, IO, etc).
-
Support
-The Web is the best-supported target platform for Dioxus.
--
-
- Because your app will be compiled to WASM you have access to browser APIs through wasm-bingen. -
- Dioxus provides hydration to resume apps that are rendered on the server. See the fullstack getting started guide for more information. -
Tooling
-To develop your Dioxus app for the web, you'll need a tool to build and serve your assets. We recommend using dioxus-cli which includes a build system, Wasm optimization, a dev server, and support hot reloading:
-cargo install dioxus-cli
-Make sure the wasm32-unknown-unknown target for rust is installed:
rustup target add wasm32-unknown-unknown
-Creating a Project
-Create a new crate:
-cargo new --bin demo
-cd demo
-Add Dioxus and the web renderer as dependencies (this will edit your Cargo.toml):
cargo add dioxus
-cargo add dioxus-web
-Edit your main.rs:
-#![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!" - } - }) -} -
And to serve our app:
-dioxus serve
-":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/custom_hooks.html b/docs/nightly/guide/en/interactivity/custom_hooks.html
deleted file mode 100644
index 56817def0..000000000
--- a/docs/nightly/guide/en/interactivity/custom_hooks.html
+++ /dev/null
@@ -1,435 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Introduction
-
Dioxus is a portable, performant, and ergonomic framework for building cross-platform user interfaces in Rust. This guide will help you get started with writing Dioxus apps for the Web, Desktop, Mobile, and more.
---#![allow(unused)] -fn main() { -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!" } - )) -} -} -
Dioxus is heavily inspired by React. If you know React, getting started with Dioxus will be a breeze.
---This guide assumes you already know some Rust! If not, we recommend reading the book to learn Rust first.
-
Features
--
-
- Desktop apps running natively (no Electron!) in less than 10 lines of code. -
- Incredibly ergonomic and powerful state management. -
- Comprehensive inline documentation – hover and guides for all HTML elements, listeners, and events. -
- Extremely memory efficient – 0 global allocations for steady-state components. -
- Multi-channel asynchronous scheduler for first-class async support. -
- And more! Read the full release post. -
Multiplatform
-Dioxus is a portable toolkit, meaning the Core implementation can run anywhere with no platform-dependent linking. Unlike many other Rust frontend toolkits, Dioxus is not intrinsically linked to WebSys. In fact, every element and event listener can be swapped out at compile time. By default, Dioxus ships with the html feature enabled, but this can be disabled depending on your target renderer.
Right now, we have several 1st-party renderers:
--
-
- WebSys (for WASM): Great support -
- Tao/Tokio (for Desktop apps): Good support -
- Tao/Tokio (for Mobile apps): Poor support -
- SSR (for generating static markup) -
- TUI/Rink (for terminal-based apps): Experimental -
Stability
-Dioxus has not reached a stable release yet.
-Web: Since the web is a fairly mature platform, we expect there to be very little API churn for web-based features.
-Desktop: APIs will likely be in flux as we figure out better patterns than our ElectronJS counterpart.
-SSR: We don't expect the SSR API to change drastically in the future.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/dynamic_rendering.html b/docs/nightly/guide/en/interactivity/dynamic_rendering.html
deleted file mode 100644
index f5088b4ae..000000000
--- a/docs/nightly/guide/en/interactivity/dynamic_rendering.html
+++ /dev/null
@@ -1,418 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Custom Hooks
-Hooks are a great way to encapsulate business logic. If none of the existing hooks work for your problem, you can write your own.
-When writing your hook, you can make a function that accepts cx: &ScopeState as a parameter to accept a scope with any Props.
Composing Hooks
-To avoid repetition, you can encapsulate business logic based on existing hooks to create a new hook.
-For example, if many components need to access an AppSettings struct, you can create a "shortcut" hook:
--#![allow(unused)] -fn main() { -fn use_settings(cx: &ScopeState) -> &UseSharedState<AppSettings> { - use_shared_state::<AppSettings>(cx).expect("App settings not provided") -} -} -
Or if you want to wrap a hook that persists reloads with the storage API, you can build on top of the use_ref hook to work with mutable state:
---#![allow(unused)] -fn main() { -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; - } -} -} -
Custom Hook Logic
-You can use cx.use_hook to build your own hooks. In fact, this is what all the standard hooks are built on!
use_hook accepts a single closure for initializing the hook. It will be only run the first time the component is rendered. The return value of that closure will be used as the value of the hook – Dioxus will take it, and store it for as long as the component is alive. On every render (not just the first one!), you will get a reference to this value.
--Note: You can implement
-Dropfor your hook value – it will be dropped then the component is unmounted (no longer in the UI)
Inside the initialization closure, you will typically make calls to other cx methods. For example:
-
-
- The
use_statehook tracks state in the hook value, and usescx.schedule_updateto make Dioxus re-render the component whenever it changes.
-
Here is a simplified implementation of the use_state hook:
--#![allow(unused)] -fn main() { -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)(); - } -} -} -
-
-
- The
use_contexthook callscx.consume_context(which would be expensive to call on every render) to get some context from the scope
-
Here is an implementation of the use_context and use_context_provider hooks:
--#![allow(unused)] -fn main() { -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 - }) -} - -} -
Hook Anti-Patterns
-When writing a custom hook, you should avoid the following anti-patterns:
--
-
- !Clone Hooks: To allow hooks to be used within async blocks, the hooks must be Clone. To make a hook clone, you can wrap data in Rc or Arc and avoid lifetimes in hooks. -
This version of use_state may seem more efficient, but it is not cloneable:
---#![allow(unused)] -fn main() { -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)(); - } -} -} -
If we try to use this hook in an async block, we will get a compile error:
---#![allow(unused)] -fn main() { -fn FutureComponent(cx: &ScopeState) -> Element { - let my_state = my_use_state(cx, || 0); - cx.spawn({ - to_owned![my_state]; - async move { - my_state.set(1); - } - }); - - todo!() -} -} -
But with the original version, we can use it in an async block:
-- --#![allow(unused)] -fn main() { -fn FutureComponent(cx: &ScopeState) -> Element { - let my_state = use_state(cx, || 0); - cx.spawn({ - to_owned![my_state]; - async move { - my_state.set(1); - } - }); - - todo!() -} -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/event_handlers.html b/docs/nightly/guide/en/interactivity/event_handlers.html
deleted file mode 100644
index 61d7a540c..000000000
--- a/docs/nightly/guide/en/interactivity/event_handlers.html
+++ /dev/null
@@ -1,316 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Improving the
-Inspecting
-The
-
-
-
-
- Dynamic Rendering
-Sometimes you want to render different things depending on the state/props. With Dioxus, just describe what you want to see using Rust control flow – the framework will take care of making the necessary changes on the fly if the state or props change!
-Conditional Rendering
-To render different elements based on a condition, you could use an if-else statement:
--#![allow(unused)] -fn main() { -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", - } - }) -} -} -
--You could also use
-matchstatements, or any Rust function to conditionally render different things.
Improving the if-else Example
-You may have noticed some repeated code in the if-else example above. Repeating code like this is both bad for maintainability and performance. Dioxus will skip diffing static elements like the button, but when switching between multiple rsx calls it cannot perform this optimization. For this example either approach is fine, but for components with large parts that are reused between conditionals, it can be more of an issue.
We can improve this example by splitting up the dynamic parts and inserting them where they are needed.
---#![allow(unused)] -fn main() { -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" - } - } -}) -} -
Inspecting Element props
-Since Element is a Option<VNode>, components accepting Element as a prop can inspect its contents, and render different things based on that. Example:
--#![allow(unused)] -fn main() { -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") - } - } -} -} -
You can't mutate the Element, but if you need a modified version of it, you can construct a new one based on its attributes/children/etc.
Rendering Nothing
-To render nothing, you can return None from a component. This is useful if you want to conditionally hide something:
--#![allow(unused)] -fn main() { -if *is_logged_in { - return None; -} - -cx.render(rsx! { - a { - "You must be logged in to comment" - } -}) -} -
This works because the Element type is just an alias for Option<VNode>
--Again, you may use a different method to conditionally return
-None. For example the boolean'sthen()function could be used.
Rendering Lists
-Often, you'll want to render a collection of components. For example, you might want to render a list of all comments on a post.
-For this, Dioxus accepts iterators that produce Elements. So we need to:
-
-
- Get an iterator over all of our items (e.g., if you have a
Vecof comments, iterate over it withiter())
- .mapthe iterator to convert each item into aLazyNodeusingrsx!(...)--
-
- Add a unique
keyattribute to each iterator item
-
-- Add a unique
- Include this iterator in the final RSX (or use it inline) -
Example: suppose you have a list of comments you want to render. Then, you can render them like this:
---#![allow(unused)] -fn main() { -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, -)) -} -
Inline for loops
-Because of how common it is to render a list of items, Dioxus provides a shorthand for this. Instead of using .iter, .map, and rsx, you can use a for` loop with a body of rsx code:
--#![allow(unused)] -fn main() { -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(), - } - } -)) -} -
The key Attribute
-Every time you re-render your list, Dioxus needs to keep track of which items go where to determine what updates need to be made to the UI.
-For example, suppose the CommentComponent had some state – e.g. a field where the user typed in a reply. If the order of comments suddenly changes, Dioxus needs to correctly associate that state with the same comment – otherwise, the user will end up replying to a different comment!
To help Dioxus keep track of list items, we need to associate each item with a unique key. In the example above, we dynamically generated the unique key. In real applications, it's more likely that the key will come from e.g. a database ID. It doesn't matter where you get the key from, as long as it meets the requirements:
--
-
- Keys must be unique in a list -
- The same item should always get associated with the same key -
- Keys should be relatively small (i.e. converting the entire Comment structure to a String would be a pretty bad key) so they can be compared efficiently -
You might be tempted to use an item's index in the list as its key. That’s what Dioxus will use if you don’t specify a key at all. This is only acceptable if you can guarantee that the list is constant – i.e., no re-ordering, additions, or deletions.
--- -Note that if you pass the key to a component you've made, it won't receive the key as a prop. It’s only used as a hint by Dioxus itself. If your component needs an ID, you have to pass it as a separate prop.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/hooks.html b/docs/nightly/guide/en/interactivity/hooks.html
deleted file mode 100644
index a16179255..000000000
--- a/docs/nightly/guide/en/interactivity/hooks.html
+++ /dev/null
@@ -1,388 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- The
-
-
-
-
- Event Handlers
-Event handlers are used to respond to user actions. For example, an event handler could be triggered when the user clicks, scrolls, moves the mouse, or types a character.
-Event handlers are attached to elements. For example, we usually don't care about all the clicks that happen within an app, only those on a particular button.
-Event handlers are similar to regular attributes, but their name usually starts with on- and they accept closures as values. The closure will be called whenever the event it listens for is triggered and will be passed that event.
For example, to handle clicks on an element, we can specify an onclick handler:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - button { - onclick: move |event| println!("Clicked! Event: {event:?}"), - "click me!" - } -}) -} -
The Event object
-Event handlers receive an Event object containing information about the event. Different types of events contain different types of data. For example, mouse-related events contain MouseData, which tells you things like where the mouse was clicked and what mouse buttons were used.
In the example above, this event data was logged to the terminal:
-Clicked! Event: UiEvent { bubble_state: Cell { value: true }, data: MouseData { coordinates: Coordinates { screen: (242.0, 256.0), client: (26.0, 17.0), element: (16.0, 7.0), page: (26.0, 17.0) }, modifiers: (empty), held_buttons: EnumSet(), trigger_button: Some(Primary) } }
-Clicked! Event: UiEvent { bubble_state: Cell { value: true }, data: MouseData { coordinates: Coordinates { screen: (242.0, 256.0), client: (26.0, 17.0), element: (16.0, 7.0), page: (26.0, 17.0) }, modifiers: (empty), held_buttons: EnumSet(), trigger_button: Some(Primary) } }
-To learn what the different event types for HTML provide, read the events module docs.
-Event propagation
-Some events will trigger first on the element the event originated at upward. For example, a click event on a button inside a div would first trigger the button's event listener and then the div's event listener.
--For more information about event propigation see the mdn docs on event bubling
-
If you want to prevent this behavior, you can call stop_propagation() on the event:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - div { - onclick: move |_event| {}, - "outer", - button { - onclick: move |event| { - // now, outer won't be triggered - event.stop_propagation(); - }, - "inner" - } - } -}) -} -
Prevent Default
-Some events have a default behavior. For keyboard events, this might be entering the typed character. For mouse events, this might be selecting some text.
-In some instances, might want to avoid this default behavior. For this, you can add the prevent_default attribute with the name of the handler whose default behavior you want to stop. This attribute can be used for multiple handlers using their name separated by spaces:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - input { - prevent_default: "oninput onclick", - } -}) -} -
Any event handlers will still be called.
---Normally, in React or JavaScript, you'd call "preventDefault" on the event in the callback. Dioxus does not currently support this behavior. Note: this means you cannot conditionally prevent default behavior based on the data in the event.
-
Handler Props
-Sometimes, you might want to make a component that accepts an event handler. A simple example would be a FancyButton component, which accepts an on_click handler:
--#![allow(unused)] -fn main() { -#[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." - })) -} -} -
Then, you can use it like any other handler:
---#![allow(unused)] -fn main() { - cx.render(rsx! { - FancyButton { - on_click: move |event| println!("Clicked! {event:?}") - } - }) -} -
-- -Note: just like any other attribute, you can name the handlers anything you want! Though they must start with
-on, for the prop to be automatically turned into anEventHandlerat the call site.You can also put custom data in the event, rather than e.g.
-MouseData
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/images/counter.png b/docs/nightly/guide/en/interactivity/images/counter.png
deleted file mode 100644
index dd89cadef..000000000
Binary files a/docs/nightly/guide/en/interactivity/images/counter.png and /dev/null differ
diff --git a/docs/nightly/guide/en/interactivity/images/counter_two_state.png b/docs/nightly/guide/en/interactivity/images/counter_two_state.png
deleted file mode 100644
index 4f77942a2..000000000
Binary files a/docs/nightly/guide/en/interactivity/images/counter_two_state.png and /dev/null differ
diff --git a/docs/nightly/guide/en/interactivity/images/meme_editor_screenshot.png b/docs/nightly/guide/en/interactivity/images/meme_editor_screenshot.png
deleted file mode 100644
index 3f7c807fb..000000000
Binary files a/docs/nightly/guide/en/interactivity/images/meme_editor_screenshot.png and /dev/null differ
diff --git a/docs/nightly/guide/en/interactivity/index.html b/docs/nightly/guide/en/interactivity/index.html
deleted file mode 100644
index c0ab8cef0..000000000
--- a/docs/nightly/guide/en/interactivity/index.html
+++ /dev/null
@@ -1,220 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Hooks and Component State
-So far our components have had no state like a normal rust functions. However, in a UI component, it is often useful to have stateful functionality to build user interactions. For example, you might want to track whether the user has opened a drop-down, and render different things accordingly.
-Hooks allow us to create state in our components. Hooks are Rust functions that take a reference to ScopeState (in a component, you can pass cx), and provide you with functionality and state.
use_state Hook
-use_state is one of the simplest hooks.
-
-
- You provide a closure that determines the initial value -
use_stategives you the current value, and a way to update it by setting it to something else
-- When the value updates,
use_statemakes the component re-render, and provides you with the new value
-
For example, you might have seen the counter example, in which state (a number) is tracked using the use_state hook:
--#![allow(unused)] -fn main() { -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!" - } - )) -} -} -
Every time the component's state changes, it re-renders, and the component function is called, so you can describe what you want the new UI to look like. You don't have to worry about "changing" anything – just describe what you want in terms of the state, and Dioxus will take care of the rest!
----
use_statereturns your value wrapped in a smart pointer of typeUseState. This is why you can both read the value and update it, even within an event handler.
You can use multiple hooks in the same component if you want:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - let mut count_a = use_state(cx, || 0); - let mut count_b = use_state(cx, || 0); - - 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--" } - )) -} -} -
Rules of Hooks
-The above example might seem a bit magic, since Rust functions are typically not associated with state. Dioxus allows hooks to maintain state across renders through a reference to ScopeState, which is why you must pass &cx to them.
But how can Dioxus differentiate between multiple hooks in the same component? As you saw in the second example, both use_state functions were called with the same parameters, so how come they can return different things when the counters are different?
--#![allow(unused)] -fn main() { - let mut count_a = use_state(cx, || 0); - let mut count_b = use_state(cx, || 0); -} -
This is only possible because the two hooks are always called in the same order, so Dioxus knows which is which. Because the order you call hooks matters, you must follow certain rules when using hooks:
--
-
- Hooks may be only used in components or other hooks (we'll get to that later) -
- On every call to the component function
-
-
-
- The same hooks must be called (except in the case of early returns, as explained later in the Error Handling chapter) -
- In the same order -
- - Hooks name's should start with
use_so you don't accidentally confuse them with regular functions
-
These rules mean that there are certain things you can't do with hooks:
-No Hooks in Conditionals
---#![allow(unused)] -fn main() { -// ❌ 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}") -} -} -
No Hooks in Closures
---#![allow(unused)] -fn main() { -// ❌ 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(); -} -
No Hooks in Loops
---#![allow(unused)] -fn main() { -// `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}"); -} -} -
use_ref Hook
-use_state is great for tracking simple values. However, you may notice in the UseState API that the only way to modify its value is to replace it with something else (e.g., by calling set, or through one of the +=, -= operators). This works well when it is cheap to construct a value (such as any primitive). But what if you want to maintain more complex data in the components state?
For example, suppose we want to maintain a Vec of values. If we stored it with use_state, the only way to add a new value to the list would be to create a new Vec with the additional value, and put it in the state. This is expensive! We want to modify the existing Vec instead.
Thankfully, there is another hook for that, use_ref! It is similar to use_state, but it lets you get a mutable reference to the contained data.
Here's a simple example that keeps a list of events in a use_ref. We can acquire write access to the state with .with_mut(), and then just .push a new value to the state:
--#![allow(unused)] -fn main() { -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!" - } - )) -} -} -
-- -The return values of
-use_stateanduse_ref(UseStateandUseRef, respectively) are in some ways similar toCellandRefCell– they provide interior mutability. However, these Dioxus wrappers also ensure that the component gets re-rendered whenever you change the state.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/router.html b/docs/nightly/guide/en/interactivity/router.html
deleted file mode 100644
index 01fe94b39..000000000
--- a/docs/nightly/guide/en/interactivity/router.html
+++ /dev/null
@@ -1,296 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Interactivity
-So far, we've learned how to describe the structure and properties of our user interfaces. However, most interfaces need to be interactive in order to be useful. In this chapter, we describe how to make a Dioxus app that responds to the user.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/sharing_state.html b/docs/nightly/guide/en/interactivity/sharing_state.html
deleted file mode 100644
index 06dfe8073..000000000
--- a/docs/nightly/guide/en/interactivity/sharing_state.html
+++ /dev/null
@@ -1,392 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Router
-In many of your apps, you'll want to have different "scenes". For a webpage, these scenes might be the different webpages with their own content. For a desktop app, these scenes might be different views in your app.
-To unify these platforms, Dioxus provides a first-party solution for scene management called Dioxus Router.
-What is it?
-For an app like the Dioxus landing page (https://dioxuslabs.com), we want to have several different scenes:
--
-
- Homepage -
- Blog -
Each of these scenes is independent – we don't want to render both the homepage and blog at the same time.
-The Dioxus router makes it easy to create these scenes. To make sure we're using the router, add the dioxus-router package to your Cargo.toml.
cargo add dioxus-router
-Using the router
-Unlike other routers in the Rust ecosystem, our router is built declaratively. This makes it possible to compose our app layout simply by arranging components.
---#![allow(unused)] -fn main() { -rsx!{ - // All of our routes will be rendered inside this Router component - Router { - // if the current location is "/home", render the Home component - Route { to: "/home", Home {} } - // if the current location is "/blog", render the Blog component - Route { to: "/blog", Blog {} } - } -} -} -
Whenever we visit this app, we will get either the Home component or the Blog component rendered depending on which route we enter at. If neither of these routes match the current location, then nothing will render.
-We can fix this one of two ways:
--
-
- A fallback 404 page -
--#![allow(unused)] -fn main() { -rsx!{ - Router { - Route { to: "/home", Home {} } - Route { to: "/blog", Blog {} } - // if the current location doesn't match any of the above routes, render the NotFound component - Route { to: "", NotFound {} } - } -} -} -
-
-
- Redirect 404 to home -
--#![allow(unused)] -fn main() { -rsx!{ - Router { - Route { to: "/home", Home {} } - Route { to: "/blog", Blog {} } - // if the current location doesn't match any of the above routes, redirect to "/home" - Redirect { from: "", to: "/home" } - } -} -} -
Links
-For our app to navigate these routes, we can provide clickable elements called Links. These simply wrap <a> elements that, when clicked, navigate the app to the given location.
--#![allow(unused)] -fn main() { -rsx!{ - Link { - to: "/home", - "Go home!" - } -} -} -
More reading
-This page is just a very brief overview of the router. For more information, check out the router book or some of the router examples.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/interactivity/user_input.html b/docs/nightly/guide/en/interactivity/user_input.html
deleted file mode 100644
index 2a7a4b793..000000000
--- a/docs/nightly/guide/en/interactivity/user_input.html
+++ /dev/null
@@ -1,270 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Sharing State
-Often, multiple components need to access the same state. Depending on your needs, there are several ways to implement this.
-Lifting State
-One approach to share state between components is to "lift" it up to the nearest common ancestor. This means putting the use_state hook in a parent component, and passing the needed values down as props.
Suppose we want to build a meme editor. We want to have an input to edit the meme caption, but also a preview of the meme with the caption. Logically, the meme and the input are 2 separate components, but they need access to the same state (the current caption).
---Of course, in this simple example, we could write everything in one component – but it is better to split everything out in smaller components to make the code more reusable, maintainable, and performant (this is even more important for larger, complex apps).
-
We start with a Meme component, responsible for rendering a meme with a given caption:
--#![allow(unused)] -fn main() { -#[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}" - } - } - } - )) -} -} -
--Note that the
-Memecomponent is unaware where the caption is coming from – it could be stored inuse_state,use_ref, or a constant. This ensures that it is very reusable – the same component can be used for a meme gallery without any changes!
We also create a caption editor, completely decoupled from the meme. The caption editor must not store the caption itself – otherwise, how will we provide it to the Meme component? Instead, it should accept the current caption as a prop, as well as an event handler to delegate input events to:
--#![allow(unused)] -fn main() { -#[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), - })) -} -} -
Finally, a third component will render the other two as children. It will be responsible for keeping the state and passing down the relevant props.
---#![allow(unused)] -fn main() { -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());}, - }, - } - }) -} -} -
Using Context
-Sometimes, some state needs to be shared between multiple components far down the tree, and passing it down through props is very inconvenient.
-Suppose now that we want to implement a dark mode toggle for our app. To achieve this, we will make every component select styling depending on whether dark mode is enabled or not.
---Note: we're choosing this approach for the sake of an example. There are better ways to implement dark mode (e.g. using CSS variables). Let's pretend CSS variables don't exist – welcome to 2013!
-
Now, we could write another use_state in the top component, and pass is_dark_mode down to every component through props. But think about what will happen as the app grows in complexity – almost every component that renders any CSS is going to need to know if dark mode is enabled or not – so they'll all need the same dark mode prop. And every parent component will need to pass it down to them. Imagine how messy and verbose that would get, especially if we had components several levels deep!
Dioxus offers a better solution than this "prop drilling" – providing context. The use_context_provider hook is similar to use_ref, but it makes it available through use_context for all children components.
First, we have to create a struct for our dark mode configuration:
---#![allow(unused)] -fn main() { -struct DarkMode(bool); -} -
Now, in a top-level component (like App), we can provide the DarkMode context to all children components:
--#![allow(unused)] -fn main() { -use_shared_state_provider(cx, || DarkMode(false)); -} -
As a result, any child component of App (direct or not), can access the DarkMode context.
--#![allow(unused)] -fn main() { -let dark_mode_context = use_shared_state::<DarkMode>(cx); -} -
---
use_contextreturnsOption<UseSharedState<DarkMode>>here. If the context has been provided, the value isSome(UseSharedState<DarkMode>), which you can call.reador.writeon, similarly toUseRef. Otherwise, the value isNone.
For example, here's how we would implement the dark mode toggle, which both reads the context (to determine what color it should render) and writes to it (to toggle dark mode):
-- --#![allow(unused)] -fn main() { -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; - }, - }, - })) -} -} -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/lib.rs b/docs/nightly/guide/en/lib.rs
deleted file mode 100644
index 97cda56a8..000000000
--- a/docs/nightly/guide/en/lib.rs
+++ /dev/null
@@ -1 +0,0 @@
-// empty (we only need this crate for the examples)
diff --git a/docs/nightly/guide/en/mark.min.js b/docs/nightly/guide/en/mark.min.js
deleted file mode 100644
index 163623188..000000000
--- a/docs/nightly/guide/en/mark.min.js
+++ /dev/null
@@ -1,7 +0,0 @@
-/*!***************************************************
-* mark.js v8.11.1
-* https://markjs.io/
-* Copyright (c) 2014–2018, Julian Kühnel
-* Released under the MIT license https://git.io/vwTVl
-*****************************************************/
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- User Input
-Interfaces often need to provide a way to input data: e.g. text, numbers, checkboxes, etc. In Dioxus, there are two ways you can work with user input.
-Controlled Inputs
-With controlled inputs, you are directly in charge of the state of the input. This gives you a lot of flexibility, and makes it easy to keep things in sync. For example, this is how you would create a controlled text input:
---#![allow(unused)] -fn main() { -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()), - } - }) -} -} -
Notice the flexibility – you can:
--
-
- Also display the same contents in another element, and they will be in sync -
- Transform the input every time it is modified (e.g. to make sure it is upper case) -
- Validate the input every time it changes -
- Have custom logic happening when the input changes (e.g. network request for autocompletion) -
- Programmatically change the value (e.g. a "randomize" button that fills the input with nonsense) -
Uncontrolled Inputs
-As an alternative to controlled inputs, you can simply let the platform keep track of the input values. If we don't tell a HTML input what content it should have, it will be editable anyway (this is built into the browser). This approach can be more performant, but less flexible. For example, it's harder to keep the input in sync with another element.
-Since you don't necessarily have the current value of the uncontrolled input in state, you can access it either by listening to oninput events (similarly to controlled components), or, if the input is part of a form, you can access the form data in the form events (e.g. oninput or onsubmit):
--#![allow(unused)] -fn main() { -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", }, - } - }) -} -} -
Submitted! UiEvent { data: FormData { value: "", values: {"age": "very old", "date": "1966", "name": "Fred"} } }
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/publishing/desktop.html b/docs/nightly/guide/en/publishing/desktop.html
deleted file mode 100644
index 1c3707617..000000000
--- a/docs/nightly/guide/en/publishing/desktop.html
+++ /dev/null
@@ -1,254 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Explicitly Required
-Automatic Conversion with
-The
-The
-The
-
-
-Improving the
-Inspecting
-The
-
-Install
-
-
-
-
-
-
- Introduction
-
Dioxus is a portable, performant, and ergonomic framework for building cross-platform user interfaces in Rust. This guide will help you get started with writing Dioxus apps for the Web, Desktop, Mobile, and more.
---#![allow(unused)] -fn main() { -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!" } - )) -} -} -
Dioxus is heavily inspired by React. If you know React, getting started with Dioxus will be a breeze.
---This guide assumes you already know some Rust! If not, we recommend reading the book to learn Rust first.
-
Features
--
-
- Desktop apps running natively (no Electron!) in less than 10 lines of code. -
- Incredibly ergonomic and powerful state management. -
- Comprehensive inline documentation – hover and guides for all HTML elements, listeners, and events. -
- Extremely memory efficient – 0 global allocations for steady-state components. -
- Multi-channel asynchronous scheduler for first-class async support. -
- And more! Read the full release post. -
Multiplatform
-Dioxus is a portable toolkit, meaning the Core implementation can run anywhere with no platform-dependent linking. Unlike many other Rust frontend toolkits, Dioxus is not intrinsically linked to WebSys. In fact, every element and event listener can be swapped out at compile time. By default, Dioxus ships with the html feature enabled, but this can be disabled depending on your target renderer.
Right now, we have several 1st-party renderers:
--
-
- WebSys (for WASM): Great support -
- Tao/Tokio (for Desktop apps): Good support -
- Tao/Tokio (for Mobile apps): Poor support -
- SSR (for generating static markup) -
- TUI/Rink (for terminal-based apps): Experimental -
Stability
-Dioxus has not reached a stable release yet.
-Web: Since the web is a fairly mature platform, we expect there to be very little API churn for web-based features.
-Desktop: APIs will likely be in flux as we figure out better patterns than our ElectronJS counterpart.
-SSR: We don't expect the SSR API to change drastically in the future.
-Getting Started
-This section will help you set up your Dioxus project!
-Prerequisites
-An Editor
-Dioxus integrates very well with the Rust-Analyzer LSP plugin which will provide appropriate syntax highlighting, code navigation, folding, and more.
-Rust
-Head over to https://rust-lang.org and install the Rust compiler.
-We strongly recommend going through the official Rust book completely. However, we hope that a Dioxus app can serve as a great first Rust project. With Dioxus, you'll learn about:
--
-
- Error handling -
- Structs, Functions, Enums -
- Closures -
- Macros -
We've put a lot of care into making Dioxus syntax familiar and easy to understand, so you won't need deep knowledge of async, lifetimes, or smart pointers until you start building complex Dioxus apps.
-Setup Guides
-Dioxus supports multiple platforms. Choose the platform you want to target below to get platform-specific setup instructions:
--
-
- Web: runs in the browser through WebAssembly -
- Server Side Rendering: renders to HTML text on the server -
- Liveview: runs on the server, renders in the browser using WebSockets -
- Desktop: runs in a web view on desktop -
- Mobile: runs in a web view on mobile -
- Terminal UI: renders text-based graphics in the terminal -
Desktop Overview
-Build a standalone native desktop app that looks and feels the same across operating systems.
-Apps built with Dioxus are typically <5mb in size and use existing system resources, so they won't hog extreme amounts of RAM or memory.
-Examples:
- -
Support
-The desktop is a powerful target for Dioxus but is currently limited in capability when compared to the Web platform. Currently, desktop apps are rendered with the platform's WebView library, but your Rust code is running natively on a native thread. This means that browser APIs are not available, so rendering WebGL, Canvas, etc is not as easy as the Web. However, native system APIs are accessible, so streaming, WebSockets, filesystem, etc are all viable APIs. In the future, we plan to move to a custom web renderer-based DOM renderer with WGPU integrations.
-Dioxus Desktop is built off Tauri. Right now there aren't any Dioxus abstractions over the menubar, handling, etc, so you'll want to leverage Tauri – mostly Wry and Tao) directly.
-Getting started
-Platform-Specific Dependencies
-Dioxus desktop renders through a web view. Depending on your platform, you might need to install some dependancies.
-Windows
-Windows Desktop apps depend on WebView2 – a library that should be installed in all modern Windows distributions. If you have Edge installed, then Dioxus will work fine. If you don't have Webview2, then you can install it through Microsoft. MS provides 3 options:
--
-
- A tiny "evergreen" bootstrapper that fetches an installer from Microsoft's CDN -
- A tiny installer that fetches Webview2 from Microsoft's CDN -
- A statically linked version of Webview2 in your final binary for offline users -
For development purposes, use Option 1.
-Linux
-Webview Linux apps require WebkitGtk. When distributing, this can be part of your dependency tree in your .rpm or .deb. However, likely, your users will already have WebkitGtk.
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev
-When using Debian/bullseye libappindicator3-dev is no longer available but replaced by libayatana-appindicator3-dev.
# on Debian/bullseye use:
-sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev
-If you run into issues, make sure you have all the basics installed, as outlined in the Tauri docs.
-MacOS
-Currently – everything for macOS is built right in! However, you might run into an issue if you're using nightly Rust due to some permissions issues in our Tao dependency (which have been resolved but not published).
-Creating a Project
-Create a new crate:
-cargo new --bin demo
-cd demo
-Add Dioxus and the desktop renderer as dependencies (this will edit your Cargo.toml):
cargo add dioxus
-cargo add dioxus-desktop
-Edit your main.rs:
-#![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); -} - -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -
Web
-Build single-page applications that run in the browser with Dioxus. To run on the Web, your app must be compiled to WebAssembly and depend on the dioxus and dioxus-web crates.
A build of Dioxus for the web will be roughly equivalent to the size of a React build (70kb vs 65kb) but it will load significantly faster because WebAssembly can be compiled as it is streamed.
-Examples:
- -
--Note: Because of the limitations of Wasm, not every crate will work with your web apps, so you'll need to make sure that your crates work without native system calls (timers, IO, etc).
-
Support
-The Web is the best-supported target platform for Dioxus.
--
-
- Because your app will be compiled to WASM you have access to browser APIs through wasm-bingen. -
- Dioxus provides hydration to resume apps that are rendered on the server. See the fullstack getting started guide for more information. -
Tooling
-To develop your Dioxus app for the web, you'll need a tool to build and serve your assets. We recommend using dioxus-cli which includes a build system, Wasm optimization, a dev server, and support hot reloading:
-cargo install dioxus-cli
-Make sure the wasm32-unknown-unknown target for rust is installed:
rustup target add wasm32-unknown-unknown
-Creating a Project
-Create a new crate:
-cargo new --bin demo
-cd demo
-Add Dioxus and the web renderer as dependencies (this will edit your Cargo.toml):
cargo add dioxus
-cargo add dioxus-web
-Edit your main.rs:
-#![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!" - } - }) -} -
And to serve our app:
-dioxus serve
-Server-Side Rendering
-For lower-level control over the rendering process, you can use the dioxus-ssr crate directly. This can be useful when integrating with a web framework that dioxus-server does not support, or pre-rendering pages.
Setup
-For this guide, we're going to show how to use Dioxus SSR with Axum.
-Make sure you have Rust and Cargo installed, and then create a new project:
-cargo new --bin demo
-cd demo
-Add Dioxus and the ssr renderer as dependencies:
-cargo add dioxus
-cargo add dioxus-ssr
-Next, add all the Axum dependencies. This will be different if you're using a different Web Framework
-cargo add tokio --features full
-cargo add axum
-Your dependencies should look roughly like this:
-[dependencies]
-axum = "0.4.5"
-dioxus = { version = "*" }
-dioxus-ssr = { version = "*" }
-tokio = { version = "1.15.0", features = ["full"] }
-Now, set up your Axum app to respond on an endpoint.
--#![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(); -} - -
And then add our endpoint. We can either render rsx! directly:
--#![allow(unused)] -fn main() { -async fn app_endpoint() -> Html<String> { - // render the rsx! macro to HTML - Html(dioxus_ssr::render_lazy(rsx! { - div { "hello world!" } - })) -} -} -
Or we can render VirtualDoms.
---#![allow(unused)] -fn main() { -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)) -} -} -
And then add our app component:
---#![allow(unused)] -fn main() { -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
And that's it!
-Multithreaded Support
-The Dioxus VirtualDom, sadly, is not currently Send. Internally, we use quite a bit of interior mutability which is not thread-safe.
-When working with web frameworks that require Send, it is possible to render a VirtualDom immediately to a String – but you cannot hold the VirtualDom across an await point. For retained-state SSR (essentially LiveView), you'll need to spawn a VirtualDom on its own thread and communicate with it via channels or create a pool of VirtualDoms.
-You might notice that you cannot hold the VirtualDom across an await point. Because Dioxus is currently not ThreadSafe, it must remain on the thread it started. We are working on loosening this requirement.
Fullstack
-Liveview
-Liveview allows apps to run on the server and render in the browser. It uses WebSockets to communicate between the server and the browser.
-Examples:
- -Support
-Liveview is currently limited in capability when compared to the Web platform. Liveview apps run on the server in a native thread. This means that browser APIs are not available, so rendering WebGL, Canvas, etc is not as easy as the Web. However, native system APIs are accessible, so streaming, WebSockets, filesystem, etc are all viable APIs.
-Setup
-For this guide, we're going to show how to use Dioxus Liveview with Axum.
-Make sure you have Rust and Cargo installed, and then create a new project:
-cargo new --bin demo
-cd app
-Add Dioxus and the liveview renderer with the Axum feature as dependencies:
-cargo add dioxus
-cargo add dioxus-liveview --features axum
-Next, add all the Axum dependencies. This will be different if you're using a different Web Framework
-cargo add tokio --features full
-cargo add axum
-Your dependencies should look roughly like this:
-[dependencies]
-axum = "0.4.5"
-dioxus = { version = "*" }
-dioxus-liveview = { version = "*", features = ["axum"] }
-tokio = { version = "1.15.0", features = ["full"] }
-Now, set up your Axum app to respond on an endpoint.
--#[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(); -} -
And then add our app component:
---#![allow(unused)] -fn main() { -fn app(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
And that's it!
-Terminal UI
-You can build a text-based interface that will run in the terminal using Dioxus.
-
--Note: this book was written with HTML-based platforms in mind. You might be able to follow along with TUI, but you'll have to adapt a bit.
-
Support
-TUI support is currently quite experimental. But, if you're willing to venture into the realm of the unknown, this guide will get you started.
--
-
- It uses flexbox for the layout -
- It only supports a subset of the attributes and elements -
- Regular widgets will not work in the tui render, but the tui renderer has its own widget components that start with a capital letter. See the widgets example -
- 1px is one character line height. Your regular CSS px does not translate -
- If your app panics, your terminal is wrecked. This will be fixed eventually -
Getting Set up
-Start by making a new package and adding Dioxus and the TUI renderer as dependancies.
-cargo new --bin demo
-cd demo
-cargo add dioxus
-cargo add dioxus-tui
-Then, edit your main.rs with the basic template.
-#![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!" - } - }) -} -
To run our app:
-cargo run
-Press "ctrl-c" to close the app. To switch from "ctrl-c" to just "q" to quit you can launch the app with a configuration to disable the default quit and use the root TuiContext to quit on your own.
--// 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!" - } - }) -} -
Mobile App
-Build a mobile app with Dioxus!
-Example: Todo App
-Support
-Mobile is currently the least-supported renderer target for Dioxus. Mobile apps are rendered with either the platform's WebView or experimentally through WGPU. WebView doesn't support animations, transparency, and native widgets.
-Mobile support is currently best suited for CRUD-style apps, ideally for internal teams who need to develop quickly but don't care much about animations or native widgets.
-This guide is primarily targeted at iOS apps, however, you can follow it while using the android guide in cargo-mobile.
Getting Set up
-Getting set up with mobile can be quite challenging. The tooling here isn't great (yet) and might take some hacking around to get things working. macOS M1 is broadly unexplored and might not work for you.
-We're going to be using cargo-mobile to build for mobile. First, install it:
cargo install --git https://github.com/BrainiumLLC/cargo-mobile
-And then initialize your app for the right platform. Use the winit template for now. Right now, there's no "Dioxus" template in cargo-mobile.
cargo mobile init
-We're going to completely clear out the dependencies it generates for us, swapping out winit with dioxus-mobile.
-[package]
-name = "dioxus-ios-demo"
-version = "0.1.0"
-authors = []
-edition = "2018"
-
-
-# leave the `lib` declaration
-[lib]
-crate-type = ["staticlib", "cdylib", "rlib"]
-
-
-# leave the binary it generates for us
-[[bin]]
-name = "dioxus-ios-demo-desktop"
-path = "gen/bin/desktop.rs"
-
-# clear all the dependencies
-[dependencies]
-mobile-entry-point = "0.1.0"
-dioxus = { version = "*"}
-dioxus-desktop = { version = "*" }
-simple_logger = "*"
-Edit your lib.rs:
-use dioxus::prelude::*; - -fn main() { - dioxus_desktop::launch(app); -} - -fn app(cx: Scope) -> Element { - cx.render(rsx!{ - div { - "hello world!" - } - }) -} -
Setting Up Hot Reload
--
-
- Hot reloading allows much faster iteration times inside of rsx calls by interpreting them and streaming the edits. -
- It is useful when changing the styling/layout of a program, but will not help with changing the logic of a program. -
- Currently the cli only implements hot reloading for the web renderer. For TUI, desktop, and LiveView you can use the hot reload macro instead. -
Web
-For the web renderer, you can use the dioxus cli to serve your application with hot reloading enabled.
-Setup
-Install dioxus-cli. -Hot reloading is automatically enabled when using the web renderer on debug builds.
-Usage
--
-
- Run: -
dioxus serve --hot-reload
--
-
- Change some code within a rsx or render macro -
- Open your localhost in a browser -
- Save and watch the style change without recompiling -
Desktop/Liveview/TUI/Server
-For desktop, LiveView, and tui, you can place the hot reload macro at the top of your main function to enable hot reloading. -Hot reloading is automatically enabled on debug builds.
-For more information about hot reloading on native platforms and configuration options see the dioxus-hot-reload crate.
-Setup
-Add the following to your main function:
--fn main() { - hot_reload_init!(); - // launch your application -} -
Usage
--
-
- Run: -
cargo run
--
-
- Change some code within a rsx or render macro -
- Save and watch the style change without recompiling -
Limitations
--
-
- The interpreter can only use expressions that existed on the last full recompile. If you introduce a new variable or expression to the rsx call, it will require a full recompile to capture the expression. -
- Components, Iterators, and some attributes can contain arbitrary rust code and will trigger a full recompile when changed. -
Describing the UI
-Dioxus is a declarative framework. This means that instead of telling Dioxus what to do (e.g. to "create an element" or "set the color to red") we simply declare what we want the UI to look like using RSX.
-You have already seen a simple example of RSX syntax in the "hello world" application:
---#![allow(unused)] -fn main() { -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
Here, we use the rsx! macro to declare that we want a div element, containing the text "Hello, world!". Dioxus takes the RSX and constructs a UI from it.
RSX Features
-RSX is very similar to HTML in that it describes elements with attributes and children. Here's an empty div element in RSX, as well as the resulting HTML:
--#![allow(unused)] -fn main() { -cx.render(rsx!(div { - // attributes / listeners - // children -})) -} -
<div></div>
-Attributes
-Attributes (and listeners) modify the behavior or appearance of the element they are attached to. They are specified inside the {} brackets, using the name: value syntax. You can provide the value as a literal in the RSX:
--#![allow(unused)] -fn main() { -cx.render(rsx!(a { - href: "https://www.youtube.com/watch?v=dQw4w9WgXcQ", - class: "primary_button", - color: "red", -})) -} -
<a href="https://www.youtube.com/watch?v=dQw4w9WgXcQ" class="primary_button" autofocus="true" style="color: red"></a>
---Note: All attributes defined in
-dioxus-htmlfollow the snake_case naming convention. They transform theirsnake_casenames to HTML'scamelCaseattributes.
--Note: Styles can be used directly outside of the
-style:attribute. In the above example,color: "red"is turned intostyle="color: red".
Custom Attributes
-Dioxus has a pre-configured set of attributes that you can use. RSX is validated at compile time to make sure you didn't specify an invalid attribute. If you want to override this behavior with a custom attribute name, specify the attribute in quotes:
---#![allow(unused)] -fn main() { - cx.render(rsx!(b { - "customAttribute": "value", - })) -} -
<b customAttribute="value">
-</b>
-Interpolation
-Similarly to how you can format Rust strings, you can also interpolate in RSX text. Use {variable} to Display the value of a variable in a string, or {variable:?} to use the Debug representation:
--#![allow(unused)] -fn main() { -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 { - "{{}}" - }, -})) -} -
<div class="country-es" position="(42, 0)">
- <div>ES</div>
- <div>42</div>
- <div>{}</div>
-</div>
-Children
-To add children to an element, put them inside the {} brackets after all attributes and listeners in the element. They can be other elements, text, or components. For example, you could have an ol (ordered list) element, containing 3 li (list item) elements, each of which contains some text:
--#![allow(unused)] -fn main() { -cx.render(rsx!(ol { - li {"First Item"} - li {"Second Item"} - li {"Third Item"} -})) -} -
<ol>
- <li>First Item</li>
- <li>Second Item</li>
- <li>Third Item</li>
-</ol>
-Fragments
-You can render multiple elements at the top level of rsx! and they will be automatically grouped.
--#![allow(unused)] -fn main() { -cx.render(rsx!( - p {"First Item"}, - p {"Second Item"}, -)) -} -
<p>First Item</p>
-<p>Second Item</p>
-Expressions
-You can include arbitrary Rust expressions as children within RSX that implements IntoDynNode. This is useful for displaying data from an iterator:
---#![allow(unused)] -fn main() { -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() }) -})) -} -
<span>DIOXUS0123456789</span>
-Loops
-In addition to iterators you can also use for loops directly within RSX:
---#![allow(unused)] -fn main() { -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}" } }) - } -}) -} -
<div>0</div>
-<div>1</div>
-<div>2</div>
-<div>0</div>
-<div>1</div>
-<div>2</div>
-If statements
-You can also use if statements without an else branch within RSX:
---#![allow(unused)] -fn main() { -cx.render(rsx!{ - // use if statements without an else - if true { - rsx!(div { "true" }) - } -}) -} -
<div>true</div>
-Special Attributes
-While most attributes are simply passed on to the HTML, some have special behaviors.
-The HTML Escape Hatch
-If you're working with pre-rendered assets, output from templates, or output from a JS library, then you might want to pass HTML directly instead of going through Dioxus. In these instances, reach for dangerous_inner_html.
For example, shipping a markdown-to-Dioxus converter might significantly bloat your final application size. Instead, you'll want to pre-render your markdown to HTML and then include the HTML directly in your output. We use this approach for the Dioxus homepage:
---#![allow(unused)] -fn main() { -// this should come from a trusted source -let contents = "live <b>dangerously</b>"; - -cx.render(rsx! { - div { - dangerous_inner_html: "{contents}", - } -}) -} -
--Note! This attribute is called "dangerous_inner_html" because it is dangerous to pass it data you don't trust. If you're not careful, you can easily expose cross-site scripting (XSS) attacks to your users.
-If you're handling untrusted input, make sure to sanitize your HTML before passing it into
-dangerous_inner_html– or just pass it to a Text Element to escape any HTML tags.
Boolean Attributes
-Most attributes, when rendered, will be rendered exactly as the input you provided. However, some attributes are considered "boolean" attributes and just their presence determines whether they affect the output. For these attributes, a provided value of "false" will cause them to be removed from the target element.
So this RSX wouldn't actually render the hidden attribute:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - div { - hidden: "false", - "hello" - } -}) -} -
<div>hello</div>
-Not all attributes work like this however. Only the following attributes have this behavior:
--
-
allowfullscreen
-allowpaymentrequest
-async
-autofocus
-autoplay
-checked
-controls
-default
-defer
-disabled
-formnovalidate
-hidden
-ismap
-itemscope
-loop
-multiple
-muted
-nomodule
-novalidate
-open
-playsinline
-readonly
-required
-reversed
-selected
-truespeed
-
For any other attributes, a value of "false" will be sent directly to the DOM.
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!
--#![allow(unused)] -fn main() { -// define a component that renders a div with the text "Hello, world!" -fn App(cx: Scope) -> Element { - cx.render(rsx! { - div { - "Hello, world!" - } - }) -} -} -
--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:
--#![allow(unused)] -fn main() { -pub fn About(cx: Scope) -> Element { - cx.render(rsx!(p { - b {"Dioxus Labs"} - " An Open Source project dedicated to making Rust UI wonderful." - })) -} -} -
Then, you can render your component in another component, similarly to how elements are rendered:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - cx.render(rsx! { - About {}, - About {}, - }) -} -} -
--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!
-
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 from a parent component -
- Cannot be memoized due to lifetime constraints -
-
Owned Props
-Owned Props are very simple – they don't borrow anything. Example:
---#![allow(unused)] -fn main() { -// 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" - } - }) -} -} -
You can then pass prop values to the component the same way you would pass attributes to an element:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - cx.render(rsx! { - Likes { - score: 42, - }, - }) -} -} -
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() 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!
--#![allow(unused)] -fn main() { -#[derive(Props)] -struct TitleCardProps<'a> { - title: &'a str, -} - -fn TitleCard<'a>(cx: Scope<'a, TitleCardProps<'a>>) -> Element { - cx.render(rsx! { - h1 { "{cx.props.title}" } - }) -} -} -
We can then use the component like this:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - let hello = "Hello Dioxus!"; - - cx.render(rsx!(TitleCard { title: hello })) -} -} -
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:
--#![allow(unused)] -fn main() { -#[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"), - })) -} -} -
Then, you can choose to either provide them or not:
---#![allow(unused)] -fn main() { -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, -// }, -} -
Explicitly Required Options
-If you want to explicitly require an Option, and not an optional prop, you can annotate it with #[props(!optional)]:
--#![allow(unused)] -fn main() { -#[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"), - })) -} -} -
Then, you have to explicitly pass either Some("str") or None:
--#![allow(unused)] -fn main() { -ExplicitOption { - title: "Some Title", - subtitle: None, -}, -ExplicitOption { - title: "Some Title", - subtitle: Some("Some Title"), -}, -// This won't compile: -// ExplicitOption { -// title: "Some Title", -// }, -} -
Default Props
-You can use #[props(default = 42)] to make a field optional and specify its default value:
--#![allow(unused)] -fn main() { -#[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}" })) -} -} -
Then, similarly to optional props, you don't have to provide it:
---#![allow(unused)] -fn main() { -DefaultComponent { - number: 5, -}, -DefaultComponent {}, -} -
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:
--#![allow(unused)] -fn main() { -#[derive(PartialEq, Props)] -struct IntoProps { - #[props(into)] - string: String, -} - -fn IntoComponent(cx: Scope<IntoProps>) -> Element { - cx.render(rsx!(h1 { "{cx.props.string}" })) -} -} -
Then, you can use it so:
---#![allow(unused)] -fn main() { -IntoComponent { - string: "some &str", -}, -} -
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:
--#![allow(unused)] -fn main() { -#[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:
--#![allow(unused)] -fn main() { -#[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.
-
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:
--#![allow(unused)] -fn main() { -#[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 - } - )) -} -} -
Then, when rendering the component, you can pass in the output of cx.render(rsx!(...)):
--#![allow(unused)] -fn main() { - cx.render(rsx! { - Clickable { - href: "https://www.youtube.com/watch?v=C-M2hs3sXGo", - body: cx.render(rsx!("How to " i {"not"} " be seen")), - } - }) -} -
--Note: Since
-Element<'a>is a borrowed prop, there will be no memoization.
--Warning: While it may compile, do not include the same
-Elementmore 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:
--#![allow(unused)] -fn main() { -#[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 - } - )) -} -} -
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!
--#![allow(unused)] -fn main() { - cx.render(rsx! { - Clickable { - href: "https://www.youtube.com/watch?v=C-M2hs3sXGo", - "How to " i {"not"} " be seen" - } - }) -} -
Interactivity
-So far, we've learned how to describe the structure and properties of our user interfaces. However, most interfaces need to be interactive in order to be useful. In this chapter, we describe how to make a Dioxus app that responds to the user.
-Event Handlers
-Event handlers are used to respond to user actions. For example, an event handler could be triggered when the user clicks, scrolls, moves the mouse, or types a character.
-Event handlers are attached to elements. For example, we usually don't care about all the clicks that happen within an app, only those on a particular button.
-Event handlers are similar to regular attributes, but their name usually starts with on- and they accept closures as values. The closure will be called whenever the event it listens for is triggered and will be passed that event.
For example, to handle clicks on an element, we can specify an onclick handler:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - button { - onclick: move |event| println!("Clicked! Event: {event:?}"), - "click me!" - } -}) -} -
The Event object
-Event handlers receive an Event object containing information about the event. Different types of events contain different types of data. For example, mouse-related events contain MouseData, which tells you things like where the mouse was clicked and what mouse buttons were used.
In the example above, this event data was logged to the terminal:
-Clicked! Event: UiEvent { bubble_state: Cell { value: true }, data: MouseData { coordinates: Coordinates { screen: (242.0, 256.0), client: (26.0, 17.0), element: (16.0, 7.0), page: (26.0, 17.0) }, modifiers: (empty), held_buttons: EnumSet(), trigger_button: Some(Primary) } }
-Clicked! Event: UiEvent { bubble_state: Cell { value: true }, data: MouseData { coordinates: Coordinates { screen: (242.0, 256.0), client: (26.0, 17.0), element: (16.0, 7.0), page: (26.0, 17.0) }, modifiers: (empty), held_buttons: EnumSet(), trigger_button: Some(Primary) } }
-To learn what the different event types for HTML provide, read the events module docs.
-Event propagation
-Some events will trigger first on the element the event originated at upward. For example, a click event on a button inside a div would first trigger the button's event listener and then the div's event listener.
--For more information about event propigation see the mdn docs on event bubling
-
If you want to prevent this behavior, you can call stop_propagation() on the event:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - div { - onclick: move |_event| {}, - "outer", - button { - onclick: move |event| { - // now, outer won't be triggered - event.stop_propagation(); - }, - "inner" - } - } -}) -} -
Prevent Default
-Some events have a default behavior. For keyboard events, this might be entering the typed character. For mouse events, this might be selecting some text.
-In some instances, might want to avoid this default behavior. For this, you can add the prevent_default attribute with the name of the handler whose default behavior you want to stop. This attribute can be used for multiple handlers using their name separated by spaces:
--#![allow(unused)] -fn main() { -cx.render(rsx! { - input { - prevent_default: "oninput onclick", - } -}) -} -
Any event handlers will still be called.
---Normally, in React or JavaScript, you'd call "preventDefault" on the event in the callback. Dioxus does not currently support this behavior. Note: this means you cannot conditionally prevent default behavior based on the data in the event.
-
Handler Props
-Sometimes, you might want to make a component that accepts an event handler. A simple example would be a FancyButton component, which accepts an on_click handler:
--#![allow(unused)] -fn main() { -#[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." - })) -} -} -
Then, you can use it like any other handler:
---#![allow(unused)] -fn main() { - cx.render(rsx! { - FancyButton { - on_click: move |event| println!("Clicked! {event:?}") - } - }) -} -
--Note: just like any other attribute, you can name the handlers anything you want! Though they must start with
-on, for the prop to be automatically turned into anEventHandlerat the call site.You can also put custom data in the event, rather than e.g.
-MouseData
Hooks and Component State
-So far our components have had no state like a normal rust functions. However, in a UI component, it is often useful to have stateful functionality to build user interactions. For example, you might want to track whether the user has opened a drop-down, and render different things accordingly.
-Hooks allow us to create state in our components. Hooks are Rust functions that take a reference to ScopeState (in a component, you can pass cx), and provide you with functionality and state.
use_state Hook
-use_state is one of the simplest hooks.
-
-
- You provide a closure that determines the initial value -
use_stategives you the current value, and a way to update it by setting it to something else
-- When the value updates,
use_statemakes the component re-render, and provides you with the new value
-
For example, you might have seen the counter example, in which state (a number) is tracked using the use_state hook:
--#![allow(unused)] -fn main() { -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!" - } - )) -} -} -
Every time the component's state changes, it re-renders, and the component function is called, so you can describe what you want the new UI to look like. You don't have to worry about "changing" anything – just describe what you want in terms of the state, and Dioxus will take care of the rest!
----
use_statereturns your value wrapped in a smart pointer of typeUseState. This is why you can both read the value and update it, even within an event handler.
You can use multiple hooks in the same component if you want:
---#![allow(unused)] -fn main() { -fn App(cx: Scope) -> Element { - let mut count_a = use_state(cx, || 0); - let mut count_b = use_state(cx, || 0); - - 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--" } - )) -} -} -
Rules of Hooks
-The above example might seem a bit magic, since Rust functions are typically not associated with state. Dioxus allows hooks to maintain state across renders through a reference to ScopeState, which is why you must pass &cx to them.
But how can Dioxus differentiate between multiple hooks in the same component? As you saw in the second example, both use_state functions were called with the same parameters, so how come they can return different things when the counters are different?
--#![allow(unused)] -fn main() { - let mut count_a = use_state(cx, || 0); - let mut count_b = use_state(cx, || 0); -} -
This is only possible because the two hooks are always called in the same order, so Dioxus knows which is which. Because the order you call hooks matters, you must follow certain rules when using hooks:
--
-
- Hooks may be only used in components or other hooks (we'll get to that later) -
- On every call to the component function
-
-
-
- The same hooks must be called (except in the case of early returns, as explained later in the Error Handling chapter) -
- In the same order -
- - Hooks name's should start with
use_so you don't accidentally confuse them with regular functions
-
These rules mean that there are certain things you can't do with hooks:
-No Hooks in Conditionals
---#![allow(unused)] -fn main() { -// ❌ 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}") -} -} -
No Hooks in Closures
---#![allow(unused)] -fn main() { -// ❌ 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(); -} -
No Hooks in Loops
---#![allow(unused)] -fn main() { -// `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}"); -} -} -
use_ref Hook
-use_state is great for tracking simple values. However, you may notice in the UseState API that the only way to modify its value is to replace it with something else (e.g., by calling set, or through one of the +=, -= operators). This works well when it is cheap to construct a value (such as any primitive). But what if you want to maintain more complex data in the components state?
For example, suppose we want to maintain a Vec of values. If we stored it with use_state, the only way to add a new value to the list would be to create a new Vec with the additional value, and put it in the state. This is expensive! We want to modify the existing Vec instead.
Thankfully, there is another hook for that, use_ref! It is similar to use_state, but it lets you get a mutable reference to the contained data.
Here's a simple example that keeps a list of events in a use_ref. We can acquire write access to the state with .with_mut(), and then just .push a new value to the state:
--#![allow(unused)] -fn main() { -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!" - } - )) -} -} -
--The return values of
-use_stateanduse_ref(UseStateandUseRef, respectively) are in some ways similar toCellandRefCell– they provide interior mutability. However, these Dioxus wrappers also ensure that the component gets re-rendered whenever you change the state.
User Input
-Interfaces often need to provide a way to input data: e.g. text, numbers, checkboxes, etc. In Dioxus, there are two ways you can work with user input.
-Controlled Inputs
-With controlled inputs, you are directly in charge of the state of the input. This gives you a lot of flexibility, and makes it easy to keep things in sync. For example, this is how you would create a controlled text input:
---#![allow(unused)] -fn main() { -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()), - } - }) -} -} -
Notice the flexibility – you can:
--
-
- Also display the same contents in another element, and they will be in sync -
- Transform the input every time it is modified (e.g. to make sure it is upper case) -
- Validate the input every time it changes -
- Have custom logic happening when the input changes (e.g. network request for autocompletion) -
- Programmatically change the value (e.g. a "randomize" button that fills the input with nonsense) -
Uncontrolled Inputs
-As an alternative to controlled inputs, you can simply let the platform keep track of the input values. If we don't tell a HTML input what content it should have, it will be editable anyway (this is built into the browser). This approach can be more performant, but less flexible. For example, it's harder to keep the input in sync with another element.
-Since you don't necessarily have the current value of the uncontrolled input in state, you can access it either by listening to oninput events (similarly to controlled components), or, if the input is part of a form, you can access the form data in the form events (e.g. oninput or onsubmit):
--#![allow(unused)] -fn main() { -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", }, - } - }) -} -} -
Submitted! UiEvent { data: FormData { value: "", values: {"age": "very old", "date": "1966", "name": "Fred"} } }
-Sharing State
-Often, multiple components need to access the same state. Depending on your needs, there are several ways to implement this.
-Lifting State
-One approach to share state between components is to "lift" it up to the nearest common ancestor. This means putting the use_state hook in a parent component, and passing the needed values down as props.
Suppose we want to build a meme editor. We want to have an input to edit the meme caption, but also a preview of the meme with the caption. Logically, the meme and the input are 2 separate components, but they need access to the same state (the current caption).
---Of course, in this simple example, we could write everything in one component – but it is better to split everything out in smaller components to make the code more reusable, maintainable, and performant (this is even more important for larger, complex apps).
-
We start with a Meme component, responsible for rendering a meme with a given caption:
--#![allow(unused)] -fn main() { -#[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}" - } - } - } - )) -} -} -
--Note that the
-Memecomponent is unaware where the caption is coming from – it could be stored inuse_state,use_ref, or a constant. This ensures that it is very reusable – the same component can be used for a meme gallery without any changes!
We also create a caption editor, completely decoupled from the meme. The caption editor must not store the caption itself – otherwise, how will we provide it to the Meme component? Instead, it should accept the current caption as a prop, as well as an event handler to delegate input events to:
--#![allow(unused)] -fn main() { -#[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), - })) -} -} -
Finally, a third component will render the other two as children. It will be responsible for keeping the state and passing down the relevant props.
---#![allow(unused)] -fn main() { -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());}, - }, - } - }) -} -} -
Using Context
-Sometimes, some state needs to be shared between multiple components far down the tree, and passing it down through props is very inconvenient.
-Suppose now that we want to implement a dark mode toggle for our app. To achieve this, we will make every component select styling depending on whether dark mode is enabled or not.
---Note: we're choosing this approach for the sake of an example. There are better ways to implement dark mode (e.g. using CSS variables). Let's pretend CSS variables don't exist – welcome to 2013!
-
Now, we could write another use_state in the top component, and pass is_dark_mode down to every component through props. But think about what will happen as the app grows in complexity – almost every component that renders any CSS is going to need to know if dark mode is enabled or not – so they'll all need the same dark mode prop. And every parent component will need to pass it down to them. Imagine how messy and verbose that would get, especially if we had components several levels deep!
Dioxus offers a better solution than this "prop drilling" – providing context. The use_context_provider hook is similar to use_ref, but it makes it available through use_context for all children components.
First, we have to create a struct for our dark mode configuration:
---#![allow(unused)] -fn main() { -struct DarkMode(bool); -} -
Now, in a top-level component (like App), we can provide the DarkMode context to all children components:
--#![allow(unused)] -fn main() { -use_shared_state_provider(cx, || DarkMode(false)); -} -
As a result, any child component of App (direct or not), can access the DarkMode context.
--#![allow(unused)] -fn main() { -let dark_mode_context = use_shared_state::<DarkMode>(cx); -} -
---
use_contextreturnsOption<UseSharedState<DarkMode>>here. If the context has been provided, the value isSome(UseSharedState<DarkMode>), which you can call.reador.writeon, similarly toUseRef. Otherwise, the value isNone.
For example, here's how we would implement the dark mode toggle, which both reads the context (to determine what color it should render) and writes to it (to toggle dark mode):
---#![allow(unused)] -fn main() { -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; - }, - }, - })) -} -} -
Custom Hooks
-Hooks are a great way to encapsulate business logic. If none of the existing hooks work for your problem, you can write your own.
-When writing your hook, you can make a function that accepts cx: &ScopeState as a parameter to accept a scope with any Props.
Composing Hooks
-To avoid repetition, you can encapsulate business logic based on existing hooks to create a new hook.
-For example, if many components need to access an AppSettings struct, you can create a "shortcut" hook:
--#![allow(unused)] -fn main() { -fn use_settings(cx: &ScopeState) -> &UseSharedState<AppSettings> { - use_shared_state::<AppSettings>(cx).expect("App settings not provided") -} -} -
Or if you want to wrap a hook that persists reloads with the storage API, you can build on top of the use_ref hook to work with mutable state:
---#![allow(unused)] -fn main() { -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; - } -} -} -
Custom Hook Logic
-You can use cx.use_hook to build your own hooks. In fact, this is what all the standard hooks are built on!
use_hook accepts a single closure for initializing the hook. It will be only run the first time the component is rendered. The return value of that closure will be used as the value of the hook – Dioxus will take it, and store it for as long as the component is alive. On every render (not just the first one!), you will get a reference to this value.
--Note: You can implement
-Dropfor your hook value – it will be dropped then the component is unmounted (no longer in the UI)
Inside the initialization closure, you will typically make calls to other cx methods. For example:
-
-
- The
use_statehook tracks state in the hook value, and usescx.schedule_updateto make Dioxus re-render the component whenever it changes.
-
Here is a simplified implementation of the use_state hook:
--#![allow(unused)] -fn main() { -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)(); - } -} -} -
-
-
- The
use_contexthook callscx.consume_context(which would be expensive to call on every render) to get some context from the scope
-
Here is an implementation of the use_context and use_context_provider hooks:
--#![allow(unused)] -fn main() { -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 - }) -} - -} -
Hook Anti-Patterns
-When writing a custom hook, you should avoid the following anti-patterns:
--
-
- !Clone Hooks: To allow hooks to be used within async blocks, the hooks must be Clone. To make a hook clone, you can wrap data in Rc or Arc and avoid lifetimes in hooks. -
This version of use_state may seem more efficient, but it is not cloneable:
---#![allow(unused)] -fn main() { -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)(); - } -} -} -
If we try to use this hook in an async block, we will get a compile error:
---#![allow(unused)] -fn main() { -fn FutureComponent(cx: &ScopeState) -> Element { - let my_state = my_use_state(cx, || 0); - cx.spawn({ - to_owned![my_state]; - async move { - my_state.set(1); - } - }); - - todo!() -} -} -
But with the original version, we can use it in an async block:
---#![allow(unused)] -fn main() { -fn FutureComponent(cx: &ScopeState) -> Element { - let my_state = use_state(cx, || 0); - cx.spawn({ - to_owned![my_state]; - async move { - my_state.set(1); - } - }); - - todo!() -} -} -
Dynamic Rendering
-Sometimes you want to render different things depending on the state/props. With Dioxus, just describe what you want to see using Rust control flow – the framework will take care of making the necessary changes on the fly if the state or props change!
-Conditional Rendering
-To render different elements based on a condition, you could use an if-else statement:
--#![allow(unused)] -fn main() { -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", - } - }) -} -} -
--You could also use
-matchstatements, or any Rust function to conditionally render different things.
Improving the if-else Example
-You may have noticed some repeated code in the if-else example above. Repeating code like this is both bad for maintainability and performance. Dioxus will skip diffing static elements like the button, but when switching between multiple rsx calls it cannot perform this optimization. For this example either approach is fine, but for components with large parts that are reused between conditionals, it can be more of an issue.
We can improve this example by splitting up the dynamic parts and inserting them where they are needed.
---#![allow(unused)] -fn main() { -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" - } - } -}) -} -
Inspecting Element props
-Since Element is a Option<VNode>, components accepting Element as a prop can inspect its contents, and render different things based on that. Example:
--#![allow(unused)] -fn main() { -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") - } - } -} -} -
You can't mutate the Element, but if you need a modified version of it, you can construct a new one based on its attributes/children/etc.
Rendering Nothing
-To render nothing, you can return None from a component. This is useful if you want to conditionally hide something:
--#![allow(unused)] -fn main() { -if *is_logged_in { - return None; -} - -cx.render(rsx! { - a { - "You must be logged in to comment" - } -}) -} -
This works because the Element type is just an alias for Option<VNode>
--Again, you may use a different method to conditionally return
-None. For example the boolean'sthen()function could be used.
Rendering Lists
-Often, you'll want to render a collection of components. For example, you might want to render a list of all comments on a post.
-For this, Dioxus accepts iterators that produce Elements. So we need to:
-
-
- Get an iterator over all of our items (e.g., if you have a
Vecof comments, iterate over it withiter())
- .mapthe iterator to convert each item into aLazyNodeusingrsx!(...)--
-
- Add a unique
keyattribute to each iterator item
-
-- Add a unique
- Include this iterator in the final RSX (or use it inline) -
Example: suppose you have a list of comments you want to render. Then, you can render them like this:
---#![allow(unused)] -fn main() { -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, -)) -} -
Inline for loops
-Because of how common it is to render a list of items, Dioxus provides a shorthand for this. Instead of using .iter, .map, and rsx, you can use a for` loop with a body of rsx code:
--#![allow(unused)] -fn main() { -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(), - } - } -)) -} -
The key Attribute
-Every time you re-render your list, Dioxus needs to keep track of which items go where to determine what updates need to be made to the UI.
-For example, suppose the CommentComponent had some state – e.g. a field where the user typed in a reply. If the order of comments suddenly changes, Dioxus needs to correctly associate that state with the same comment – otherwise, the user will end up replying to a different comment!
To help Dioxus keep track of list items, we need to associate each item with a unique key. In the example above, we dynamically generated the unique key. In real applications, it's more likely that the key will come from e.g. a database ID. It doesn't matter where you get the key from, as long as it meets the requirements:
--
-
- Keys must be unique in a list -
- The same item should always get associated with the same key -
- Keys should be relatively small (i.e. converting the entire Comment structure to a String would be a pretty bad key) so they can be compared efficiently -
You might be tempted to use an item's index in the list as its key. That’s what Dioxus will use if you don’t specify a key at all. This is only acceptable if you can guarantee that the list is constant – i.e., no re-ordering, additions, or deletions.
---Note that if you pass the key to a component you've made, it won't receive the key as a prop. It’s only used as a hint by Dioxus itself. If your component needs an ID, you have to pass it as a separate prop.
-
Router
-In many of your apps, you'll want to have different "scenes". For a webpage, these scenes might be the different webpages with their own content. For a desktop app, these scenes might be different views in your app.
-To unify these platforms, Dioxus provides a first-party solution for scene management called Dioxus Router.
-What is it?
-For an app like the Dioxus landing page (https://dioxuslabs.com), we want to have several different scenes:
--
-
- Homepage -
- Blog -
Each of these scenes is independent – we don't want to render both the homepage and blog at the same time.
-The Dioxus router makes it easy to create these scenes. To make sure we're using the router, add the dioxus-router package to your Cargo.toml.
cargo add dioxus-router
-Using the router
-Unlike other routers in the Rust ecosystem, our router is built declaratively. This makes it possible to compose our app layout simply by arranging components.
---#![allow(unused)] -fn main() { -rsx!{ - // All of our routes will be rendered inside this Router component - Router { - // if the current location is "/home", render the Home component - Route { to: "/home", Home {} } - // if the current location is "/blog", render the Blog component - Route { to: "/blog", Blog {} } - } -} -} -
Whenever we visit this app, we will get either the Home component or the Blog component rendered depending on which route we enter at. If neither of these routes match the current location, then nothing will render.
-We can fix this one of two ways:
--
-
- A fallback 404 page -
--#![allow(unused)] -fn main() { -rsx!{ - Router { - Route { to: "/home", Home {} } - Route { to: "/blog", Blog {} } - // if the current location doesn't match any of the above routes, render the NotFound component - Route { to: "", NotFound {} } - } -} -} -
-
-
- Redirect 404 to home -
--#![allow(unused)] -fn main() { -rsx!{ - Router { - Route { to: "/home", Home {} } - Route { to: "/blog", Blog {} } - // if the current location doesn't match any of the above routes, redirect to "/home" - Redirect { from: "", to: "/home" } - } -} -} -
Links
-For our app to navigate these routes, we can provide clickable elements called Links. These simply wrap <a> elements that, when clicked, navigate the app to the given location.
--#![allow(unused)] -fn main() { -rsx!{ - Link { - to: "/home", - "Go home!" - } -} -} -
More reading
-This page is just a very brief overview of the router. For more information, check out the router book or some of the router examples.
-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.
UseFuture
-use_future lets you run an async closure, and provides you with its result.
For example, we can make an API request (using reqwest) inside use_future:
--#![allow(unused)] -fn main() { -let future = use_future(cx, (), |_| async move { - reqwest::get("https://dog.ceo/api/breeds/image/random") - .await - .unwrap() - .json::<ApiResponse>() - .await -}); -} -
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:
---#![allow(unused)] -fn main() { -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..." } }, -}) -} -
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:
--#![allow(unused)] -fn main() { -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 -}); -} -
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.
--#![allow(unused)] -fn main() { -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:
--#![allow(unused)] -fn main() { -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 to create a clone of the hook handle which can be moved into the async closure.
---#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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().awaitstatement you will need to extend the [Stream] trait (used by [UnboundedReceiver]) by adding 'futures_util' as a dependency to your project and adding theuse 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.
---#![allow(unused)] -fn main() { -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 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.
---#![allow(unused)] -fn main() { -static USERNAME: Atom<String> = |_| "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.
---#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -fn Child(cx: Scope) -> Element { - let sync_task = use_coroutine_handle::<SyncAction>(cx); - - sync_task.send(SyncAction::SetUsername); -} -} -
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:
--#![allow(unused)] -fn main() { - 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", - } - }) -} -
--Note:
-spawnwill 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:
---#![allow(unused)] -fn main() { - cx.spawn(async { - let _ = tokio::spawn(async {}).await; - - let _ = tokio::task::spawn_local(async { - // some !Send work - }) - .await; - }); -} -
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 -
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:
--#![allow(unused)] -fn main() { -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 thetrytrait gets upgraded.
--#![allow(unused)] -fn main() { -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.
---#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -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).
---#![allow(unused)] -fn main() { -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.
---#![allow(unused)] -fn main() { -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.
---#![allow(unused)] -fn main() { -enum InputError { - None, - TooLong, - TooShort, -} - -static INPUT_ERROR: Atom<InputError> = |_| InputError::None; -} -
Then, in our top level component, we want to explicitly handle the possible error state for this part of the tree.
---#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -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.
-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.
---#![allow(unused)] -fn main() { - // ❌ 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!" } - )) -} -
Incorrect Iterator Keys
-As described in the dynamic rendering chapter, list items must have unique keys that are associated with the same items across renders. This helps Dioxus associate state with the contained components and ensures good diffing performance. Do not omit keys, unless you know that the list will never change.
---#![allow(unused)] -fn main() { - 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}" } - )) - } - }) -} -
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.
-Publishing
-Publishing
-Congrats! You've made your first Dioxus app that actually does some pretty cool stuff. This app uses your operating system's WebView library, so it's portable to be distributed for other platforms.
-In this section, we'll cover how to bundle your app for macOS, Windows, and Linux.
-Install cargo-bundle
-The first thing we'll do is install cargo-bundle. This extension to cargo will make it very easy to package our app for the various platforms.
According to the cargo-bundle github page,
"cargo-bundle is a tool used to generate installers or app bundles for GUI executables built with cargo. It can create .app bundles for Mac OS X and iOS, .deb packages for Linux, and .msi installers for Windows (note however that iOS and Windows support is still experimental). Support for creating .rpm packages (for Linux) and .apk packages (for Android) is still pending."
-To install, simply run
-cargo install cargo-bundle
Setting up your project
-To get a project setup for bundling, we need to add some flags to our Cargo.toml file.
[package]
-name = "example"
-# ...other fields...
-
-[package.metadata.bundle]
-name = "DogSearch"
-identifier = "com.dogs.dogsearch"
-version = "1.0.0"
-copyright = "Copyright (c) Jane Doe 2016. All rights reserved."
-category = "Developer Tool"
-short_description = "Easily search for Dog photos"
-long_description = """
-This app makes it quick and easy to browse photos of dogs from over 200 bree
-"""
-Building
-Following cargo-bundle's instructions, we simply cargo-bundle --release to produce a final app with all the optimizations and assets builtin.
Once you've ran cargo-bundle --release, your app should be accessible in
target/release/bundle/<platform>/.
For example, a macOS app would look like this:
-
Nice! And it's only 4.8 Mb – extremely lean!! Because Dioxus leverages your platform's native WebView, Dioxus apps are extremely memory efficient and won't waste your battery.
---Note: not all CSS works the same on all platforms. Make sure to view your app's CSS on each platform – or web browser (Firefox, Chrome, Safari) before publishing.
-
Publishing with Github Pages
-To build our app and publish it to Github:
--
-
- Make sure GitHub Pages is set up for your repo -
- Build your app with
trunk build --release(include--public-url <repo-name>to update asset prefixes if using a project site)
- - Move your generated HTML/CSS/JS/Wasm from
distinto the folder configured for Github Pages
- - Add and commit with git -
- Push to GitHub -
Fullstack development
-So far you have learned about three different approaches to target the web with Dioxus:
--
-
- Client-side rendering with dioxus-web -
- Server-side rendering with dioxus-liveview -
- Server-side static HTML generation with dioxus-ssr -
Summary of Existing Approaches
-Each approach has its tradeoffs:
-Client-side rendering
--
-
-
-
With Client side rendering, you send the entire content of your application to the client, and then the client generates all of the HTML of the page dynamically.
-
- -
-
This means that the page will be blank until the JavaScript bundle has loaded and the application has initialized. This can result in slower first render times and makes the page less SEO-friendly.
-
-
--SEO stands for Search Engine Optimization. It refers to the practice of making your website more likely to appear in search engine results. Search engines like Google and Bing use web crawlers to index the content of websites. Most of these crawlers are not able to run JavaScript, so they will not be able to index the content of your page if it is rendered client-side.
-
-
-
- Client-side rendered applications need to use weakly typed requests to communicate with the server -
--Client-side rendering is a good starting point for most applications. It is well supported and makes it easy to communicate with the client/browser APIs
-
Liveview
--
-
-
-
Liveview rendering communicates with the server over a WebSocket connection. It essentially moves all of the work that Client-side rendering does to the server.
-
- -
-
This makes it easy to communicate with the server, but more difficult to communicate with the client/browser APIS.
-
- -
-
Each interaction also requires a message to be sent to the server and back which can cause issues with latency.
-
- -
-
Because Liveview uses a websocket to render, the page will be blank until the WebSocket connection has been established and the first renderer has been sent form the websocket. Just like with client side rendering, this can make the page less SEO-friendly.
-
- -
-
Because the page is rendered on the server and the page is sent to the client piece by piece, you never need to send the entire application to the client. The initial load time can be faster than client-side rendering with large applications because Liveview only needs to send a constant small websocket script regardless of the size of the application.
-
-
--Liveview is a good fit for applications that already need to communicate with the server frequently (like real time collaborative apps), but don't need to communicate with as many client/browser APIs
-
Server-side rendering
--
-
- Server-side rendering generates all of the HTML of the page on the server before the page is sent to the client. This means that the page will be fully rendered when it is sent to the client. This results in a faster first render time and makes the page more SEO-friendly. However, it only works for static pages. -
--Server-side rendering is not a good fit for purely static sites like a blog
-
A New Approach
-Each of these approaches has its tradeoffs. What if we could combine the best parts of each approach?
--
-
- Fast initial render time like SSR -
- Works well with SEO like SSR -
- Type safe easy communication with the server like Liveview -
- Access to the client/browser APIs like Client-side rendering -
- Fast interactivity like Client-side rendering -
We can achieve this by rendering the initial page on the server (SSR) and then taking over rendering on the client (Client-side rendering). Taking over rendering on the client is called hydration.
-Finally, we can use server functions to communicate with the server in a type-safe way.
-This approach uses both the dioxus-web and dioxus-ssr crates. To integrate those two packages and axum, warp, or salvo, Dioxus provides the dioxus-fullstack crate.
--This guide assumes you read the Web guide and installed the Dioxus-cli
-
Getting Started
-Setup
-For this guide, we're going to show how to use Dioxus with Axum, but dioxus-fullstack also integrates with the Warp and Salvo web frameworks.
Make sure you have Rust and Cargo installed, and then create a new project:
-cargo new --bin demo
-cd demo
-Add dioxus and dioxus-fullstack as dependencies:
cargo add dioxus
-cargo add dioxus-fullstack --features axum, ssr
-Next, add all the Axum dependencies. This will be different if you're using a different Web Framework
-cargo add tokio --features full
-cargo add axum
-Your dependencies should look roughly like this:
-[dependencies]
-axum = "*"
-dioxus = { version = "*" }
-dioxus-fullstack = { version = "*", features = ["axum", "ssr"] }
-tokio = { version = "*", features = ["full"] }
-Now, set up your Axum app to serve the Dioxus app.
--#![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!" } - }) -} -
Now, run your app with cargo run and open http://localhost:8080 in your browser. You should see a server-side rendered page with a counter.
Hydration
-Right now, the page is static. We can't interact with the buttons. To fix this, we can hydrate the page with dioxus-web.
First, modify your Cargo.toml to include two features, one for the server called ssr, and one for the client called web.
[dependencies]
-# Common dependancies
-dioxus = { version = "*" }
-dioxus-fullstack = { version = "*" }
-
-# Web dependancies
-dioxus-web = { version = "*", features=["hydrate"], optional = true }
-
-# Server dependancies
-axum = { version = "0.6.12", optional = true }
-tokio = { version = "1.27.0", features = ["full"], optional = true }
-
-[features]
-default = []
-ssr = ["axum", "tokio", "dioxus-fullstack/axum"]
-web = ["dioxus-web"]
-Next, we need to modify our main.rs to use either hydrate on the client or render on the server depending on the active features.
-#![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!" } - }) -} -
Now, build your client-side bundle with dioxus build --features web and run your server with cargo run --features ssr. You should see the same page as before, but now you can interact with the buttons!
Sycronizing props between the server and client
-Let's make the initial count of the counter dynamic based on the current page.
-Modifying the server
-To do this, we must remove the serve_dioxus_application and replace it with a custom implementation of its four key functions:
--
-
- Serve static WASM and JS files with serve_static_assets -
- Register server functions with register_server_fns (more information on server functions later) -
- Connect to the hot reload server with connect_hot_reload -
- A custom route that uses SSRState to server-side render the application -
Modifying the client
-The only thing we need to change on the client is the props. dioxus-fullstack will automatically serialize the props it uses to server render the app and send them to the client. In the client section of main.rs, we need to add get_root_props_from_document to deserialize the props before we hydrate the app.
-#![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!" } - }) -} -
Now, build your client-side bundle with dioxus build --features web and run your server with cargo run --features ssr. Navigate to http://localhost:8080/1 and you should see the counter start at 1. Navigate to http://localhost:8080/2 and you should see the counter start at 2.
Communicating with the server
-dixous-server provides server functions that allow you to call an automatically generated API on the server from the client as if it were a local function.
To make a server function, simply add the #[server(YourUniqueType)] attribute to a function. The function must:
-
-
- Be an async function -
- Have arguments and a return type that both implement serialize and deserialize (with serde). -
- Return a
Resultwith an error type of ServerFnError
-
You must call register on the type you passed into the server macro in your main function before starting your server to tell Dioxus about the server function.
Let's continue building on the app we made in the getting started guide. We will add a server function to our app that allows us to double the count on the server.
-First, add serde as a dependency:
-cargo add serde
-Next, add the server function to your main.rs:
-#![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; - - // Register the server function before starting the server - DoubleServer::register().unwrap(); - - 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) -} -
Now, build your client-side bundle with dioxus build --features web and run your server with cargo run --features ssr. You should see a new button that multiplies the count by 2.
Conclusion
-That's it! You've created a full-stack Dioxus app. You can find more examples of full-stack apps and information about how to integrate with other frameworks and desktop renderers in the dioxus-fullstack examples directory.
-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:
--
-
- Handle the stream of edits generated by updates to the virtual DOM -
- 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 or tui renderer as a starting point for your custom renderer.
-Templates
-Dioxus is built around the concept of Templates. 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:
--#![allow(unused)] -fn main() { -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 where the LoadTemplate, CreatePlaceholder, and CreateTextNode mutations pushes a new "real" DOM node onto the stack and AppendChildren, InsertAfter, InsertBefore, ReplacePlaceholder, and 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
An Example
-For the sake of understanding, let's consider this example – a very simple UI declaration:
---#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -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
-
This template will be sent to the renderer in the list of templates supplied with the mutations the first time it is used. Any time the renderer encounters a 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:
-<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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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.
--#![allow(unused)] -fn main() { -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:
---#![allow(unused)] -fn main() { -[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:
-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.
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.
Native Core
-If you are creating a renderer in rust, the 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:
---#![allow(unused)] -fn main() { -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:
-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:
// 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
-}
-Lets take a look at how to implement the State trait for a simple renderer.
---#![allow(unused)] -fn main() { -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 - } -} -} -
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.
--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:?}"); - }); - } - }) -} -
Layout
-For most platforms, the layout of the Elements will stay the same. The layout_attributes module provides a way to apply HTML attributes a Taffy 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.
--#![allow(unused)] -fn main() { -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); -} -} -
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.
-Contributing
-Development happens in the Dioxus GitHub repository. 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).
-GitHub discussions can be used as a place to ask for help or talk about features. You can also join our Discord channel where some development discussion happens.
-Improving Docs
-If you'd like to improve the docs, PRs are welcome! Both Rust docs (source) and this guide (source) 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 for inspiration. Once you are done, add your library to the awesome dioxus list or share it in the #I-made-a-thing channel on Discord.
Bugs & Features
-If you've fixed an open issue, feel free to submit a PR! You can also take a look at the roadmap and work on something in there. Consider reaching out 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 -
cargo fmt --all
--
-
- All code is formatted with rustfmt -
cargo check --workspace --examples --tests
--
-
- All code is linted with Clippy -
cargo clippy --workspace --examples --tests -- -D warnings
--
-
- Crates that use unsafe are checked for undefined behavior with 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-coreanddioxus-native-core.
-
cargo miri test --package dioxus-core --test miri_stress
-cargo miri test --package dioxus-native-core --test miri_native
--
-
- Rust analyzer can be very helpful for quick feedback in your IDE. -
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: A Render that Runs Dioxus applications natively, but renders them with the system webview -
- Mobile: A Render that Runs Dioxus applications natively, but renders them with the system webview. This is currently a copy of the desktop render -
- Web: Renders Dioxus applications in the browser by compiling to WASM and manipulating the DOM -
- Liveview: A Render that Runs on the server, and renders using a websocket proxy in the browser -
- Rink: A Renderer that renders a HTML-like tree into a terminal -
- TUI: A Renderer that uses Rink to render a Dioxus application in a terminal -
- Blitz-Core: An experimental native renderer that renders a HTML-like tree using WGPU. -
- Blitz: An experimental native renderer that uses Blitz-Core to render a Dioxus application using WGPU. -
- SSR: A Render that Runs Dioxus applications on the server, and renders them to HTML -
State Management/Hooks
--
-
- Hooks: A collection of common hooks for Dioxus applications -
- Signals: A experimental state management library for Dioxus applications. This currently contains a
Copyversion of UseRef
- - Dioxus STD: A collection of platform agnostic hooks to interact with system interfaces (The clipboard, camera, etc.). -
- Fermi: A global state management library for Dioxus applications. -Router: A client-side router for Dioxus applications -
Core utilities
--
-
- core: The core virtual dom implementation every Dioxus application uses
-
-
-
- You can read more about the archetecture of the core in this blog post and the custom renderer section of the guide -
- - RSX: The core parsing for RSX used for hot reloading, autoformatting, and the macro -
- core-macro: The rsx! macro used to write Dioxus applications. (This is a wrapper over the RSX crate) -
- HTML macro: A html-like alternative to the RSX macro -
Native Renderer Utilities
--
-
- 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 -
- - native-core-macro: A helper macro for native core -
- Taffy: Layout engine powering Blitz-Core, Rink, and Bevy UI -
Web renderer tooling
--
-
- HTML: defines html specific elements, events, and attributes -
- Interpreter: defines browser bindings used by the web and desktop renderers -
Developer tooling
--
-
- 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 -
- autofmt: Formats RSX code -
- rsx-rosetta: Handles conversion between HTML and RSX -
- CLI: A Command Line Interface and VSCode extension to assist with Dioxus usage -
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.
--//! Example: README.md showcase -//! -//! The example from the README.md. - -use dioxus::prelude::*; - -fn main() { - dioxus_desktop::launch(app); -} - -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!" } - }) -} -
The rsx! Macro
-Before the Rust compiler runs the program, it will expand all macros. Here is what the hello world example looks like expanded:
--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: Default::default(), - 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), - ]), - } - }, - ), - ) -} -
The rsx macro separates the static parts of the rsx (the template) and the dynamic parts (the dynamic_nodes and dynamic_attributes).
-The static template only contains the parts of the rsx that cannot change at runtime with holes for the dynamic parts:
-The dynamic_nodes and dynamic_attributes are the parts of the rsx that can change at runtime:
-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 and create a virtual dom with the root component. This guide will not explain the renderer in-depth, but you can read more about it in the 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.
-The Virtual Dom roughly looks like this:
---#![allow(unused)] -fn main() { -pub struct VirtualDom { - // All the templates that have been created or set durring 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? -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 an node is created in the Virtual Dom, a ElementId is passed along with the mutation to the renderer to identify the node. These ids are used by the Virtual Dom to reference that nodes 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 the 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:
--
-
- They store the state of hooks used by the component -
- They store the state for the context API -
- They store the current and previous VNode that was rendered for diffing -
The Initial Render
-The root scope is created and rebuilt:
--
-
- The root component is run -
- The root component returns a VNode -
- Mutations for the VNode are created and added to the mutation list (this may involve creating new child components) -
- The VNode is stored in the root scope -
After the root scope is built, the mutations are sent to the renderer to be applied to the dom.
-After the initial render, the root scope looks like this:
-Waiting for Events
-The Virtual Dom will only ever rerender 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.
-There are generally two ways a scope is marked as dirty:
--
-
- The renderer triggers an event: This causes an event listener to be called if needed which may mark a component as dirty -
- The renderer calls wait for work: This polls futures which may mark a component as dirty -
Once at least one scope is marked as dirty, the renderer can call render_with_deadline to diff the dirty scopes.
Diffing Scopes
-If the user clicked the "up high" button, the root scope would be marked as dirty by the use_state hook. Once the desktop renderer calls render_with_deadline, the root scope would be diffed.
To start the diffing process, the component is run. After the root component is run it will look like this:
-Next, the Virtual Dom will compare the new VNode with the previous VNode and only update the parts of the tree that have changed.
-When a component is re-rendered, the Virtual Dom will compare the new VNode with the previous VNode and only update the parts of the tree that have changed.
-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)
-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, and how it uses bump allocation to efficiently allocate VNodes. If need more information about the Virtual Dom, you can read the code of the core crate or reach out to us on Discord.
-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.hookprovides 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. -
- - Hooks: the hooks crate has the most common use cases, but
-
-
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 -
-
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.
-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
--
-
- -Release of Dioxus Core -
- -Upgrade documentation to include more theory and be more comprehensive -
- -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
--
-
- -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)
--
-
- -Translation from HTML into RSX -
- -Dev server -
- -Live reload -
- -Translation from JSX into RSX -
- -Hot module replacement -
- -Code splitting -
- -Asset macros -
- -Css pipeline -
- -Image pipeline -
Essential hooks
--
-
- -Router -
- -Global state management -
- -Resize observer -
Work in Progress
-Build Tool
-We are currently working on our own build tool called Dioxus 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. This will allow you to build apps that are rendered natively for iOS, Android, and Desktop.
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/publishing/index.html b/docs/nightly/guide/en/publishing/index.html
deleted file mode 100644
index 92c09a72a..000000000
--- a/docs/nightly/guide/en/publishing/index.html
+++ /dev/null
@@ -1,219 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Install
-
-
-
-
- Publishing
-Congrats! You've made your first Dioxus app that actually does some pretty cool stuff. This app uses your operating system's WebView library, so it's portable to be distributed for other platforms.
-In this section, we'll cover how to bundle your app for macOS, Windows, and Linux.
-Install cargo-bundle
-The first thing we'll do is install cargo-bundle. This extension to cargo will make it very easy to package our app for the various platforms.
According to the cargo-bundle github page,
"cargo-bundle is a tool used to generate installers or app bundles for GUI executables built with cargo. It can create .app bundles for Mac OS X and iOS, .deb packages for Linux, and .msi installers for Windows (note however that iOS and Windows support is still experimental). Support for creating .rpm packages (for Linux) and .apk packages (for Android) is still pending."
-To install, simply run
-cargo install cargo-bundle
Setting up your project
-To get a project setup for bundling, we need to add some flags to our Cargo.toml file.
[package]
-name = "example"
-# ...other fields...
-
-[package.metadata.bundle]
-name = "DogSearch"
-identifier = "com.dogs.dogsearch"
-version = "1.0.0"
-copyright = "Copyright (c) Jane Doe 2016. All rights reserved."
-category = "Developer Tool"
-short_description = "Easily search for Dog photos"
-long_description = """
-This app makes it quick and easy to browse photos of dogs from over 200 bree
-"""
-Building
-Following cargo-bundle's instructions, we simply cargo-bundle --release to produce a final app with all the optimizations and assets builtin.
Once you've ran cargo-bundle --release, your app should be accessible in
target/release/bundle/<platform>/.
For example, a macOS app would look like this:
-
Nice! And it's only 4.8 Mb – extremely lean!! Because Dioxus leverages your platform's native WebView, Dioxus apps are extremely memory efficient and won't waste your battery.
--- -Note: not all CSS works the same on all platforms. Make sure to view your app's CSS on each platform – or web browser (Firefox, Chrome, Safari) before publishing.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/publishing/web.html b/docs/nightly/guide/en/publishing/web.html
deleted file mode 100644
index d5f281b7a..000000000
--- a/docs/nightly/guide/en/publishing/web.html
+++ /dev/null
@@ -1,227 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Publishing
- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/nightly/guide/en/searcher.js b/docs/nightly/guide/en/searcher.js
deleted file mode 100644
index d2b0aeed3..000000000
--- a/docs/nightly/guide/en/searcher.js
+++ /dev/null
@@ -1,483 +0,0 @@
-"use strict";
-window.search = window.search || {};
-(function search(search) {
- // Search functionality
- //
- // You can use !hasFocus() to prevent keyhandling in your key
- // event handlers while the user is typing their search.
-
- if (!Mark || !elasticlunr) {
- return;
- }
-
- //IE 11 Compatibility from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith
- if (!String.prototype.startsWith) {
- String.prototype.startsWith = function(search, pos) {
- return this.substr(!pos || pos < 0 ? 0 : +pos, search.length) === search;
- };
- }
-
- var search_wrap = document.getElementById('search-wrapper'),
- searchbar = document.getElementById('searchbar'),
- searchbar_outer = document.getElementById('searchbar-outer'),
- searchresults = document.getElementById('searchresults'),
- searchresults_outer = document.getElementById('searchresults-outer'),
- searchresults_header = document.getElementById('searchresults-header'),
- searchicon = document.getElementById('search-toggle'),
- content = document.getElementById('content'),
-
- searchindex = null,
- doc_urls = [],
- results_options = {
- teaser_word_count: 30,
- limit_results: 30,
- },
- search_options = {
- bool: "AND",
- expand: true,
- fields: {
- title: {boost: 1},
- body: {boost: 1},
- breadcrumbs: {boost: 0}
- }
- },
- mark_exclude = [],
- marker = new Mark(content),
- current_searchterm = "",
- URL_SEARCH_PARAM = 'search',
- URL_MARK_PARAM = 'highlight',
- teaser_count = 0,
-
- SEARCH_HOTKEY_KEYCODE = 83,
- ESCAPE_KEYCODE = 27,
- DOWN_KEYCODE = 40,
- UP_KEYCODE = 38,
- SELECT_KEYCODE = 13;
-
- function hasFocus() {
- return searchbar === document.activeElement;
- }
-
- function removeChildren(elem) {
- while (elem.firstChild) {
- elem.removeChild(elem.firstChild);
- }
- }
-
- // Helper to parse a url into its building blocks.
- function parseURL(url) {
- var a = document.createElement('a');
- a.href = url;
- return {
- source: url,
- protocol: a.protocol.replace(':',''),
- host: a.hostname,
- port: a.port,
- params: (function(){
- var ret = {};
- var seg = a.search.replace(/^\?/,'').split('&');
- var len = seg.length, i = 0, s;
- for (;i
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Publishing with Github Pages
-To build our app and publish it to Github:
--
-
- Make sure GitHub Pages is set up for your repo -
- Build your app with
trunk build --release(include--public-url <repo-name>to update asset prefixes if using a project site)
- - Move your generated HTML/CSS/JS/Wasm from
distinto the folder configured for Github Pages
- - Add and commit with git -
- Push to GitHub -