Elements and Lifecycle

Elements and Lifecycle

Element is the runtime node type. It is used by both application components and renderer components.

Creating and Mounting

create_element::<C>(props) creates an element for a component type.

let props = build_props!(ButtonProps(
    .disabled = false,
    .on_click = None,
));
let element = create_element::<Button>(props);

Most code uses layout! instead.

mount_root(&element) mounts an element without a parent:

mount_root(&layout! { App });

Unmounting

element.unmount() recursively unmounts children, runs unmount callbacks, removes the element from its parent, and clears remaining mount/place callbacks.

element.on_unmount(|| {
    log::debug!("removed");
});

Renderer components use this hook to remove host objects and event listeners.

Host Handles

A renderer component can attach a host object to an element:

element.provide_handle(html_element);

The handle is stored as Shared<dyn Any>. Callers can inspect or downcast it:

if let Some(handle) = element.handle() {
    if let Ok(input) = handle.downcast::<HtmlInputElement>() {
        // use input
    }
}

Handles let descendants find their nearest host parent or predecessor even when some Nestix components, such as Fragment, do not create host objects.

Placement

on_place registers a callback that receives Placement:

element.on_place(closure!([node] |placement| {
    if let Some(pred) = &placement.pred {
        // insert after predecessor
    } else if let Some(parent) = &placement.parent {
        // append to parent
    }
}));

Placement contains:

• pred: the previous host handle in the nearest list, if any;
• parent: the nearest ancestor host handle, if any;
• index: this element's index in the nearest list, if any.

Nestix notifies placement after mount and when reconciliation changes list or fragment order.

after_mount

after_mount runs once after the component's output has mounted.

element.after_mount(|| {
    log::debug!("mounted");
});

The callback set is drained after it runs.

Context

Context values can be provided by ContextProvider. See Built-in Components for details.

layout! {
    ContextProvider::<Theme>(theme) {
        AppContent
    }
}

Tree Navigation Used by Renderers

The following methods support placement:

• handle(): this element's host handle, if any;
• parent_handle(): nearest ancestor host handle;
• pred_handle(): previous host handle in the nearest list;
• last_handle(): last host handle in this element's subtree;
• index(): index in the nearest list.

Most application code does not need these methods.