Crate dioxus_core

Expand description

§dioxus-core

dioxus-core provides a fast and featureful VirtualDom implementation for Rust.

use dioxus_core::prelude::*;
use dioxus_core::*;

let mut vdom = VirtualDom::new(app);
let real_dom = SomeRenderer::new();

loop {
    tokio::select! {
        evt = real_dom.event() => {
            let evt = Event::new(evt, true);
            vdom.runtime().handle_event("onclick", evt, ElementId(0))
        },
        _ = vdom.wait_for_work() => {}
    }
    vdom.render_immediate(&mut real_dom.apply())
}

§Features

A virtualdom is an efficient and flexible tree data structure that allows you to manage state for a graphical user interface. The Dioxus VirtualDom is perhaps the most fully-featured virtualdom implementation in Rust and powers renderers running across Web, Desktop, Mobile, SSR, TUI, LiveView, and more. When you use the Dioxus VirtualDom, you immediately enable users of your renderer to leverage the wide ecosystem of Dioxus components, hooks, and associated tooling.

Some features of dioxus-core include:

UI components are just functions
State is provided by hooks
Deep integration with async
Strong focus on performance
Integrated hotreloading support
Extensible system for UI elements and their attributes

If you are just starting, check out the Guides first.

§Understanding the implementation

dioxus-core is designed to be a lightweight crate that. It exposes a number of flexible primitives without being deeply concerned about the intracices of state management itself. We provide a number of useful abstractions built on these primitives in the dioxus-hooks crate as well as the dioxus-signals crate.

The important abstractions to understand are:

The VirtualDom
The Component and its Properties
Handling events
Working with async
Suspense

§Usage

The dioxus crate exports the rsx macro which transforms a helpful, simpler syntax of Rust.

First, start with your app:

use dioxus::prelude::*;

// First, declare a root component
fn app() -> Element {
    rsx!{
        div { "hello world" }
    }
}

fn main() {
    // Next, create a new VirtualDom using this app as the root component.
    let mut dom = VirtualDom::new(app);

    // The initial render of the dom will generate a stream of edits for the real dom to apply
    let mutations = dom.rebuild_to_vec();
}

§Contributing

Check out the website section on contributing.
Report issues on our issue tracker.
Join the discord and ask questions!

§License

This project is licensed under the MIT license.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Dioxus by you, shall be licensed as MIT, without any additional terms or conditions.

Re-exports§

pub use crate::innerlude::vdom_is_rendering;
pub use crate::innerlude::AnyValue;
pub use crate::innerlude::MarkerWrapper;
pub use const_format;

Modules§

prelude: The purpose of this module is to alleviate imports of many common types

Structs§

Attribute: An attribute on a DOM node, such as id="my-thing" or href="https://example.com"
CapturedError: An instance of an error captured by a descendant component.
ElementId: An Element’s unique identifier.
Event: A wrapper around some generic data that handles the event’s state
Mutations: A static list of mutations that can be applied to the DOM. Note: this list does not contain any Any attribute values
NoOpMutations: A struct that ignores all mutations
Runtime: A global runtime that is shared across all scopes that provides the async runtime and context API
ScopeId: A component’s unique identifier.
ScopeState: A component’s rendered state.
Task: A task’s unique identifier.
Template: A static layout of a UI tree that describes a set of dynamic and static nodes.
VComponent: An instance of a child component
VNode: A reference to a template along with any context needed to hydrate it
VNodeInner: A reference to a template along with any context needed to hydrate it
VPlaceholder: A placeholder node, used by suspense and fragments
VText: A text node
VirtualDom: A virtual node system that progresses user events and diffs UI trees.

Enums§

AttributeValue: Any of the built-in values that the Dioxus VirtualDom supports as dynamic attributes on elements
DynamicNode: A node created at runtime
Mutation: A Mutation represents a single instruction for the renderer to use to modify the UI tree to match the state of the Dioxus VirtualDom.
TemplateAttribute: An attribute of the TemplateNode, created at compile time
TemplateNode: A statically known node in a layout.

Traits§

ComponentFunction: Any component that implements the ComponentFn trait can be used as a component.
HasAttributes: A trait for anything that has a dynamic list of attributes
IntoDynNode: A trait that allows various items to be converted into a dynamic node for the rsx macro
LaunchConfig: A marker trait for platform configs. We use this marker to make sure that the user doesn’t accidentally pass in a config builder instead of the config
Properties: Every “Props” used for a component must implement the Properties trait. This trait gives some hints to Dioxus on how to memoize the props and some additional optimizations that can be made. We strongly encourage using the derive macro to implement the Properties trait automatically.
SpawnIfAsync: A helper trait for Callbacks that allows functions to accept a Callback that may return an async block which will automatically be spawned.
WriteMutations: Something that can handle the mutations that are generated by the diffing process and apply them to the Real DOM

Functions§

Fragment: Create inline fragments using Component syntax.
Ok: A helper function for an Ok result that can be either a boxed error or a value This is useful to avoid having to use Ok<T, CapturedError> everywhere
fc_to_builder: This utility function launches the builder method so that the rsx! macro can use the typed-builder pattern to initialize a component’s props.
generation: Get the current render since the inception of this component
schedule_update: Schedule an update for the current component
schedule_update_any: Schedule an update for any component given its ScopeId.
use_hook: Store a value between renders. The foundational hook for all other hooks.

Type Aliases§

Component: A Component is a function that takes Properties and returns an Element.
Element: An Element is a possibly-none VNode created by calling render on ScopeId or ScopeState.
Result: A type alias for a result that can be either a boxed error or a value This is useful to avoid having to use Result<T, CapturedError> everywhere

Crate dioxus_coreCopy item path