Crate dioxus_core

Expand description

§dioxus-core

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

use dioxus_core::{VirtualDom, Event, Element, Mutations, VNode, ElementId};

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::SuspenseBoundary;
pub use crate::innerlude::SuspenseBoundary;
pub use const_format;

Macros§

anyhow: Construct an ad-hoc error from a string or existing non-anyhow error value.
bail: Return early with an error.

Structs§

Attribute: An attribute on a DOM node, such as id="my-thing" or href="https://example.com"
Callback: The callback type generated by the rsx! macro when an on field is specified for components.
CapturedError: An anyhow::Error wrapped in an Arc so it can be cheaply cloned and passed around.
ElementId: An Element’s unique identifier.
ErrorContext: A context with information about suspended components
Event: A wrapper around some generic data that handles the event’s state
ListenerCallback: An owned callback type used in AttributeValue::Listener.
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
ReactiveContext: Reactivity
Runtime: A global runtime that is shared across all scopes that provides the async runtime and context API
RuntimeGuard: A guard for a new runtime. This must be used to override the current runtime when importing components from a dynamic library that has it’s own runtime.
ScopeId: A component’s unique identifier.
ScopeState: A component’s rendered state.
Subscribers: A list of ReactiveContexts that are subscribed. This is used to notify subscribers when the value changes.
SuspendedFuture: A task that has been suspended which may have an optional loading placeholder
SuspenseBoundaryProps: Properties for the SuspenseBoundary() component.
SuspenseContext: A context with information about suspended components
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.
RenderError: An error that can occur while rendering a component
TemplateAttribute: An attribute of the TemplateNode, created at compile time
TemplateNode: A statically known node in a layout.

Traits§

AnyhowContext: Provides the context method for Result.
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
IntoAttributeValue: A value that can be converted into an attribute value
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.
SubscriberList: A list of subscribers that can be notified when the value changes. This is used to track when the value changes and notify subscribers.
SuperFrom: A enhanced version of the From trait that allows with more flexibility.
SuperInto: A enhanced version of the Into trait that allows with more flexibility.
WriteMutations: Something that can handle the mutations that are generated by the diffing process and apply them to the Real DOM

Functions§

ErrorBoundary: Create a new error boundary component that catches any errors thrown from child components
Fragment: Create inline fragments using Component syntax.
Ok: Equivalent to Ok::<_, dioxus::CapturedError>(value).
SuspenseBoundary: Suspense Boundaries let you render a fallback UI while a child component is suspended.
consume_context: Consume context from the current scope
consume_context_from_scope: Consume context from the current scope
current_owner: Returns the current owner. This owner will be used to drop any Copy state that is created by the generational-box crate.
current_scope_id: Get the current scope id
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.
has_context: Check if the current scope has a context
needs_update: Mark the current scope as dirty, causing it to re-render.
needs_update_any: Mark the current scope as dirty, causing it to re-render.
parent_scope: Get the parent of the current scope if it exists.
provide_context: Provide context to the current scope
provide_root_context: Provide a context to the root scope
queue_effect: Queue an effect to run after the next render. You generally shouldn’t need to interact with this function directly. use_effect will call this function for you.
remove_future: Informs the scheduler that this task is no longer needed and should be removed.
schedule_update: Schedule an update for the current component.
schedule_update_any: Schedule an update for any component given its ScopeId.
spawn: Spawns the future and returns the Task. This task will automatically be canceled when the component is dropped.
spawn_forever: Spawn a future that Dioxus won’t clean up when this component is unmounted
spawn_isomorphic: Start a new future on the same thread as the rest of the VirtualDom.
suspend: Suspended the current component on a specific task and then return None
throw_error: Throw a CapturedError into the current scope. The error will bubble up to the nearest crate::ErrorBoundary() or the root of the app.
try_consume_context: Consume context from the current scope
use_after_render: Push this function to be run after the next render
use_before_render: A hook that allows you to insert a “before render” function.
use_drop: Creates a callback that will be run before the component is removed. This can be used to clean up side effects from the component (created with use_effect).
use_hook: Store a value between renders. The foundational hook for all other hooks.
use_hook_with_cleanup: Use a hook with a cleanup function
with_owner: Run a closure with the given owner.

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.
EventHandler: The callback type generated by the rsx! macro when an on field is specified for components.
Result: A result type with a default error of CapturedError.