dioxus/packages/core/README.md
Evan Almloff 0127501dbf
Improve inline docs (#2460)
Improve inline docs

* improve incorrect event handler return error message

* Improve event handler docs

* document the eval functions

* document spawn and common spawn errors

* fix event handler docs

* add notes about how you use attributes and elements in rsx

* add doc aliases for attributes and events we rename

* add some more aliases for common search terms

* don't doc ignore any public examples in core

* don't ignore public doc examples in ssr

* don't ignore examples in the dioxus package readme

* add a warning when you launch without a renderer enabled

* fix some outdated element docs

* add a bunch of examples to resource

* add notes about desktop events

* add more docs for use_resource

* add on_unimplemented hint to Dependency

* fix some unresolved links

* add examples to each of the router traits

* add not implemented errors for router traits

* add an example to the routable trait

* expand rsx macro docs

* improve memo docs

* update the dioxus readme

* mention dioxus crate features in the docs

* fix a bunch of doc tests

* fix html doc tests

* fix router doc tests

* fix dioxus signals doc tests

* fix dioxus ssr doc tests

* fix use_future example in the hooks cheat sheet

* add a javascript alias for eval

* fix hook explanation values

* remove unused embed-doc-image dependency
2024-06-06 18:15:17 -07:00

3.3 KiB

dioxus-core

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

# tokio::runtime::Runtime::new().unwrap().block_on(async {
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() => vdom.handle_event("onclick", evt, ElementId(0), true),
        _ = vdom.wait_for_work() => {}
    }
    vdom.render_immediate(&mut real_dom.apply())
}

# fn app() -> Element { None }
# struct SomeRenderer; impl SomeRenderer { fn new() -> SomeRenderer { SomeRenderer } async fn event(&self) -> std::rc::Rc<dyn std::any::Any> { unimplemented!() } fn apply(&self) -> Mutations { Mutations::default() } }
# });

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 proivde 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::dioxus_core::Mutations;
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

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.