Struct dioxus_core::prelude::ScopeState

pub struct ScopeState { /* private fields */ }

Every component in Dioxus is represented by a ScopeState.

Scopes contain the state for hooks, the component’s props, and other lifecycle information.

Scopes are allocated in a generational arena. As components are mounted/unmounted, they will replace slots of dead components. The actual contents of the hooks, though, will be allocated with the standard allocator. These should not allocate as frequently.

We expose the Scope type so downstream users can traverse the Dioxus VirtualDOM for whatever use case they might have.

Implementations

impl ScopeState

pub fn height(&self) -> u32

Get the height of this Scope - IE the number of scopes above it.

A Scope with a height of 0 is the root scope - there are no other scopes above it.

Example

let mut dom = VirtualDom::new(|cx|  cx.render(rsx!{ div {} }));
dom.rebuild();

let base = dom.base_scope();

assert_eq!(base.height(), 0);

pub fn parent(&self) -> Option<ScopeId>

Get the Parent of this Scope within this Dioxus VirtualDOM.

This ID is not unique across Dioxus VirtualDOMs or across time. IDs will be reused when components are unmounted.

The base component will not have a parent, and will return None.

Example

let mut dom = VirtualDom::new(|cx|  cx.render(rsx!{ div {} }));
dom.rebuild();

let base = dom.base_scope();

assert_eq!(base.parent(), None);

pub fn scope_id(&self) -> ScopeId

Get the ID of this Scope within this Dioxus VirtualDOM.

This ID is not unique across Dioxus VirtualDOMs or across time. IDs will be reused when components are unmounted.

Example

let mut dom = VirtualDom::new(|cx|  cx.render(rsx!{ div {} }));
dom.rebuild();
let base = dom.base_scope();

assert_eq!(base.scope_id(), 0);

pub fn scheduler_channel(&self) -> UnboundedSender<SchedulerMsg>

Get a handle to the raw update scheduler channel

pub fn schedule_update(&self) -> Arc<dyn Fn() + Send + Sync + 'static>

Create a subscription that schedules a future render for the reference component

Notice: you should prefer using prepare_update and get_scope_id

pub fn schedule_update_any(&self) -> Arc<dyn Fn(ScopeId) + Send + Sync>

Schedule an update for any component given its ScopeId.

A component’s ScopeId can be obtained from use_hook or the ScopeState::scope_id method.

This method should be used when you want to schedule an update for a component

pub fn needs_update(&self)

Get the ScopeId of a mounted component.

ScopeId is not unique for the lifetime of the VirtualDom - a ScopeId will be reused if a component is unmounted.

pub fn needs_update_any(&self, id: ScopeId)

Get the ScopeId of a mounted component.

ScopeId is not unique for the lifetime of the VirtualDom - a ScopeId will be reused if a component is unmounted.

pub fn root_node(&self) -> &VNode<'_>

Get the Root Node of this scope

pub fn provide_context<T: 'static + Clone>(&self, value: T) -> T

This method enables the ability to expose state to children further down the VirtualDOM Tree.

This is a “fundamental” operation and should only be called during initialization of a hook.

For a hook that provides the same functionality, use use_provide_context and use_consume_context instead.

When the component is dropped, so is the context. Be aware of this behavior when consuming the context via Rc/Weak.

Example

struct SharedState(&'static str);

static App: Component = |cx| {
    cx.use_hook(|_| cx.provide_context(SharedState("world")));
    rsx!(cx, Child {})
}

static Child: Component = |cx| {
    let state = cx.consume_state::<SharedState>();
    rsx!(cx, div { "hello {state.0}" })
}

pub fn provide_root_context<T: 'static + Clone>(&self, value: T) -> T

Provide a context for the root component from anywhere in your app.

Example

struct SharedState(&'static str);

static App: Component = |cx| {
    cx.use_hook(|_| cx.provide_root_context(SharedState("world")));
    rsx!(cx, Child {})
}

static Child: Component = |cx| {
    let state = cx.consume_state::<SharedState>();
    rsx!(cx, div { "hello {state.0}" })
}

pub fn consume_context<T: 'static + Clone>(&self) -> Option<T>

Try to retrieve a SharedState with type T from the any parent Scope.

pub fn push_future(&self, fut: impl Future<Output = ()> + 'static) -> TaskId

Pushes the future onto the poll queue to be polled after the component renders.

pub fn spawn(&self, fut: impl Future<Output = ()> + 'static)

Spawns the future but does not return the TaskId

pub fn spawn_forever(&self, fut: impl Future<Output = ()> + 'static) -> TaskId

Spawn a future that Dioxus will never clean up

This is good for tasks that need to be run after the component has been dropped.

pub fn remove_future(&self, id: TaskId)

Informs the scheduler that this task is no longer needed and should be removed on next poll.

pub fn render<'src>(&'src self, rsx: LazyNodes<'src, '_>) -> Option<VNode<'src>>

Take a lazy VNode structure and actually build it with the context of the VDom’s efficient VNode allocator.

This function consumes the context and absorb the lifetime, so these VNodes must be returned.

Example

fn Component(cx: Scope<Props>) -> Element {
    // Lazy assemble the VNode tree
    let lazy_nodes = rsx!("hello world");

    // Actually build the tree and allocate it
    cx.render(lazy_tree)
}

pub fn use_hook<'src, State: 'static>(
    &'src self,
    initializer: impl FnOnce(usize) -> State
) -> &'src mut State

Store a value between renders

This is the foundational hook for all other hooks.

• Initializer: closure used to create the initial hook state
• Runner: closure used to output a value every time the hook is used

To “cleanup” the hook, implement Drop on the stored hook value. Whenever the component is dropped, the hook will be dropped as well.

Example

// use_ref is the simplest way of storing a value between renders
fn use_ref<T: 'static>(initial_value: impl FnOnce() -> T) -> &RefCell<T> {
    use_hook(|| Rc::new(RefCell::new(initial_value())))
}