Struct dioxus_core::nodebuilder::ElementBuilder

pub struct ElementBuilder<'a, Listeners, Attributes, Children> where
    Listeners: 'a + AsRef<[Listener<'a>]>,
    Attributes: 'a + AsRef<[Attribute<'a>]>,
    Children: 'a + AsRef<[VNode<'a>]>,  { /* fields omitted */ }

A virtual DOM element builder.

Typically constructed with element-specific constructors, eg the div function for building <div> elements or the button function for building <button> elements.

Implementations

impl<'a> ElementBuilder<'a, Vec<'a, Listener<'a>>, Vec<'a, Attribute<'a>>, Vec<'a, VNode<'a>>>

pub fn new<B>(bump: B, tag_name: &'a str) -> Self where
    B: Into<&'a Bump>, 

Create a new ElementBuilder for an element with the given tag name.

In general, only use this constructor if the tag is dynamic (i.e. you might build a <div> or you might build a <span> and you don’t know until runtime). Prefer using the tag-specific constructors instead: div(bump) or span(bump), etc.

Example

use dioxus::{builder::*, bumpalo::Bump};

let b = Bump::new();

let tag_name = if flip_coin() {
    "div"
} else {
    "span"
};

let my_element_builder = ElementBuilder::new(&b, tag_name);

impl<'a, Listeners, Attributes, Children> ElementBuilder<'a, Listeners, Attributes, Children> where
    Listeners: 'a + AsRef<[Listener<'a>]>,
    Attributes: 'a + AsRef<[Attribute<'a>]>,
    Children: 'a + AsRef<[VNode<'a>]>, 

pub fn listeners<L>(
    self,
    listeners: L
) -> ElementBuilder<'a, L, Attributes, Children> where
    L: 'a + AsRef<[Listener<'a>]>, 

Set the listeners for this element.

You can use this method to customize the backing storage for listeners, for example to use a fixed-size array instead of the default dynamically-sized bumpalo::collections::Vec.

Any listeners already added to the builder will be overridden.

Example

use dioxus::{builder::*, bumpalo::Bump};

let b = Bump::new();

// Create a `<div>` with a fixed-size array of two listeners.
let my_div = div(&b)
    .listeners([
        on(&b, "click", |root, vdom, event| {
            // ...
        }),
        on(&b, "dblclick", |root, vdom, event| {
            // ...
        }),
    ])
    .finish();

pub fn attributes<A>(
    self,
    attributes: A
) -> ElementBuilder<'a, Listeners, A, Children> where
    A: 'a + AsRef<[Attribute<'a>]>, 

Set the attributes for this element.

You can use this method to customize the backing storage for attributes, for example to use a fixed-size array instead of the default dynamically-sized bumpalo::collections::Vec.

Any attributes already added to the builder will be overridden.

Example

use dioxus::{builder::*, bumpalo::Bump, Attribute};

let b = Bump::new();

// Create a `<div>` with a fixed-size array of two attributes.
let my_div = div(&b)
    .attributes([
        attr("id", "my-div"),
        attr("class", "notification"),
    ])
    .finish();

pub fn children<C>(
    self,
    children: C
) -> ElementBuilder<'a, Listeners, Attributes, C> where
    C: 'a + AsRef<[VNode<'a>]>, 

Set the children for this element.

You can use this method to customize the backing storage for children, for example to use a fixed-size array instead of the default dynamically-sized bumpalo::collections::Vec.

Any children already added to the builder will be overridden.

Example

use dioxus::{builder::*, bumpalo::Bump};

let b = Bump::new();

// Create a `<div>` with a fixed-size array of two `<span>` children.
let my_div = div(&b)
    .children([
        span(&b).finish(),
        span(&b).finish(),
    ])
    .finish();

pub fn namespace(self, namespace: Option<&'a str>) -> Self

Set the namespace for this element.

Example

use dioxus::{builder::*, bumpalo::Bump};

let b = Bump::new();

// Create a `<td>` tag with an xhtml namespace
let my_td = td(&b)
    .namespace(Some("http://www.w3.org/1999/xhtml"))
    .finish();

pub fn key(self, key: u32) -> Self

Set this element’s key.

When diffing sets of siblings, if an old sibling and new sibling share a key, then they will always reuse the same physical DOM VNode. This is important when using CSS animations, web components, third party JS, or anything else that makes the diffing implementation observable.

Do not use keys if such a scenario does not apply. Keyed diffing is generally more expensive than not, since it is putting greater constraints on the diffing algorithm.

Invariants You Must Uphold

The key may not be u32::MAX, which is a reserved key value.

Keys must be unique among siblings.

All sibling VNodes must be keyed, or they must all not be keyed. You may not mix keyed and unkeyed siblings.

Example

use dioxus::{builder::*, bumpalo::Bump};

let b = Bump::new();

let my_li = li(&b)
    .key(1337)
    .finish();

pub fn finish(self) -> VNode<'a>

Create the virtual DOM VNode described by this builder.

Example

use dioxus::{builder::*, bumpalo::Bump, VNode};

let b = Bump::new();

// Start with a builder...
let builder: ElementBuilder<_, _, _> = div(&b);

// ...and finish it to create a virtual DOM VNode!
let my_div: VNode = builder.finish();

impl<'a, Attributes, Children> ElementBuilder<'a, Vec<'a, Listener<'a>>, Attributes, Children> where
    Attributes: 'a + AsRef<[Attribute<'a>]>,
    Children: 'a + AsRef<[VNode<'a>]>, 

pub fn on(
    self,
    event: &'static str,
    callback: impl Fn(VirtualEvent) + 'a
) -> Self

Add a new event listener to this element.

The event string specifies which event will be listened for. The callback function is the function that will be invoked if the specified event occurs.

Example

use dioxus::{builder::*, bumpalo::Bump};

let b = Bump::new();

// A button that does something when clicked!
let my_button = button(&b)
    .on("click", |root, vdom, event| {
        // ...
    })
    .finish();

impl<'a, Listeners, Children> ElementBuilder<'a, Listeners, Vec<'a, Attribute<'a>>, Children> where
    Listeners: 'a + AsRef<[Listener<'a>]>,
    Children: 'a + AsRef<[VNode<'a>]>, 

pub fn attr(self, name: &'static str, value: &'a str) -> Self

Add a new attribute to this element.

Example

use dioxus::{builder::*, bumpalo::Bump};

let b = Bump::new();

// Create the `<div id="my-div"/>` element.
let my_div = div(&b).attr("id", "my-div").finish();

pub fn bool_attr(self, name: &'static str, should_add: bool) -> Self

Conditionally add a “boolean-style” attribute to this element.

If the should_add parameter is true, then adds an attribute with the given name and an empty string value. If the should_add parameter is false, then the attribute is not added.

This method is useful for attributes whose semantics are defined by whether or not the attribute is present or not, and whose value is ignored. Example attributes like this include:

• checked
• hidden
• selected

Example

use dioxus::{builder::*, bumpalo::Bump};
use js_sys::Math;

let b = Bump::new();

// Create the `<div>` that is randomly hidden 50% of the time.
let my_div = div(&b)
    .bool_attr("hidden", Math::random() >= 0.5)
    .finish();

impl<'a, Listeners, Attributes> ElementBuilder<'a, Listeners, Attributes, Vec<'a, VNode<'a>>> where
    Listeners: 'a + AsRef<[Listener<'a>]>,
    Attributes: 'a + AsRef<[Attribute<'a>]>, 

pub fn child(self, child: VNode<'a>) -> Self

Add a new child to this element.

Example

use dioxus::{builder::*, bumpalo::Bump};
use js_sys::Math;

let b = Bump::new();

// Create `<p><span></span></p>`.
let my_div = p(&b)
    .child(span(&b).finish())
    .finish();

Trait Implementations

impl<'a, Listeners: Clone, Attributes: Clone, Children: Clone> Clone for ElementBuilder<'a, Listeners, Attributes, Children> where
    Listeners: 'a + AsRef<[Listener<'a>]>,
    Attributes: 'a + AsRef<[Attribute<'a>]>,
    Children: 'a + AsRef<[VNode<'a>]>, 

fn clone(&self) -> ElementBuilder<'a, Listeners, Attributes, Children>

Returns a copy of the value.

pub fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a, Listeners: Debug, Attributes: Debug, Children: Debug> Debug for ElementBuilder<'a, Listeners, Attributes, Children> where
    Listeners: 'a + AsRef<[Listener<'a>]>,
    Attributes: 'a + AsRef<[Attribute<'a>]>,
    Children: 'a + AsRef<[VNode<'a>]>, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.