Crate ambient_element

Element is a React-inspired virtual tree library for the Ambient runtime.

It is backed by the Ambient ECS; the virtual tree is converted into a real tree of entities and components. When the tree is updated, it is compared to the previous tree, and only the differences are applied to the ECS. This can be used for UI, as well as any other tree-like data structure that you want to be able to update efficiently.

Idioms

By convention, most ElementComponents define an el method that returns an Element of that type. This el takes the properties to make it easy to both construct the component and instantiate it as an Element.

In addition to this, ElementComponentExt adds an el method to all ElementComponents that converts them to an Element.

This means that an ElementComponent that looks like this

#[element_component]
fn MyComponent(hooks: &mut Hooks, a: u32, b: String) -> Element {
   // ...
}

can be instantiated as an Element using either of these methods:

MyComponent { a: 42, b: "hello".to_string() }.el()

or

MyComponent::el(42, "hello".to_string())

Passing data in

To pass data into the root of an Element tree, pass the data into its properties when constructing it and/or update the root of the tree using ElementTree::migrate_root.

To receive data from an Element tree, we recommend you use messaging. This includes sending messages to the server and/or standard messaging channels in Rust (e.g. std::sync::mpsc::channel). We do not generally recommend trying to send data out of the tree directly, as this can be difficult to reason about.

Macros

to_owned

Shorthand for let x = x.to_owned();

Structs

Element

A rendered ElementComponent instance.

ElementTree

A tree of instantiated Elements.

Group

Wrap multiple Elements in a flat hierarchy.

Hooks

Hooks are a way to hook into the state and lifecycle of an Element.

Memo

Memoize the ElementComponent, such that it is only re-rendered if the component changes.

ShareableElementTree

A shareable element tree. This is used to share the same tree between multiple contexts.

Wrap

Wraps the inner Element. This is useful for introducing an intermediate component node in a tree.

Traits

AnyCloneable

A trait for types that can be converted to Any and can also be cloned.

ElementComponent

The base trait for all element components. These are similar to React components.

ElementComponentExt

A convenience trait for converting an ElementComponent into an Element.

ElementComponentName

Contains the name of the type implementing ElementComponent.

Functions

ambient_system

The systems required to drive ElementTrees.

element

Element: The identifier of the Element that controls this entity.

element_tree

The element tree state for an entity.

element_unmanaged_children

Element unmanaged children: If this is set, the user is expected to manage the children of the Element themselves.

init_components

Initialize the components for the module

render_parented_with_component

Render the given tree underneath id.

Type Aliases

DespawnFn

The return type of a function passed to Hooks::use_spawn. This function is called when the Element is unmounted/despawned; use it to clean up any resources.

Setter

Helper type for a callback that sets some value.

Attribute Macros

element_component

Helper macro to implement a ElementComponent with a pure free function.