zgui

Children and slots

Take content from the caller — Children, ChildrenFn, named slots, and children closures with let.

A component that wraps or arranges content takes that content from its caller. Use Children for content built once, ChildrenFn for content built more than once, and slots when a component has several regions to fill.

Accept children

Declare a prop of type Children. The caller's children block becomes its value.

use zgui::prelude::*;

/// A bordered region with a heading.
#[component]
fn Panel(
    /// The heading.
    #[prop(into)]
    title: String,
    /// The content.
    children: Children,
) -> impl IntoView {
    view! {
        column(class = "panel") {
            label(class = "panel__title") {{title}}
            box(class = "panel__body") {{children.into_view_once()}}
        }
    }
}
view! {
    Panel(title = "Storage") {
        text {"41 GB used"}
        text {"9 GB free"}
    }
}

Children wraps an FnOnce, so you build it once, with into_view_once(), where the content belongs.

MethodWhat it does
Children::new(f)wraps an FnOnce() -> AnyView
Children::from_view(v)wraps an existing view
into_view_once()consumes it and returns the view

Make children optional

Declare the prop as an optional Option<Children>:

#[component]
fn Separator(
    /// What stands between two things, if not the default.
    #[prop(optional)]
    children: Option<Children>,
) -> impl IntoView {
    match children {
        Some(children) => children.into_view_once(),
        None => AnyView::new("/"),
    }
}
view! { Separator() }        // renders "/"
view! { Separator {"—"} }    // renders "—"

Build children more than once

Use ChildrenFn when the content may be built more than once: it appears in two places, or it is removed and shown again. This tooltip builds its bubble again each time it opens, using the view's if:

#[component]
fn Tooltip(
    /// The bubble's content.
    children: ChildrenFn,
) -> impl IntoView {
    let open = RwSignal::new(false);

    view! {
        box(
            on:pointer_enter = move |_| open.set(true),
            on:pointer_leave = move |_| open.set(false)
        ) {
            if move || open.get() {
                box(class = "tooltip") {{children.view()}}
            }
        }
    }
}
MethodWhat it does
ChildrenFn::new(f)wraps an Fn() -> AnyView
view()builds the content; can be called any number of times

ChildrenFn is Clone and converts into Children. Prefer Children when you need the content only once, because the type tells readers it is built once.

Fill several regions with slots

A component with more than one region to fill can declare slots. A slot is a struct marked #[slot]:

use zgui::prelude::*;

/// The heading of a [`Card`].
#[slot]
pub struct CardHeader {
    /// What the heading shows.
    children: Children,
}

/// A card with an optional heading.
#[component(slot_aware)]
pub fn Card(
    /// The heading, if any.
    #[prop(optional)]
    card_header: Option<CardHeader>,
    children: Children,
) -> impl IntoView {
    let heading = card_header.map(|header| header.children.into_view_once());

    view! {
        column(class = "card") {
            {heading}
            box(class = "card__body") {{children.into_view_once()}}
        }
    }
}
view! {
    Card {
        CardHeader(slot) {"Total"}
        "£12.00"
    }
}

Three rules connect a slot to its parent:

  1. The slot child carries the slot attribute: CardHeader(slot) { … }.
  2. It fills the prop named after its type in snake case: CardHeader fills card_header. To fill a prop with a different name, write CardHeader(slot = "header").
  3. The parent component needs #[component(slot_aware)]. Without it, the compiler tells you to add it.

A slot's fields are props and take the same #[prop(...)] attributes as component arguments. The struct must have named fields. Slots can nest: a slot child of a slot fills that slot's prop.

A slot accepts only its own props, class, let: and slot. Listeners, attributes and states belong on an element inside the slot's children, and the compiler points you there.

Two Children props, or two nested components, often read better than slots. Use a slot when the region is part of the parent's structure and does not make sense as a component of its own.

Pass a value to the children

When the content depends on a value the component supplies, take a closure as the children prop:

#[component]
fn Repeat<F>(
    /// How many times to repeat.
    times: usize,
    /// Called once per repetition, with the index.
    children: F,
) -> impl IntoView
where
    F: Fn(usize) -> AnyView + 'static,
{
    let items: Vec<AnyView> = (0..times).map(&children).collect();
    view! { {items} }
}

The caller names the closure's argument with let::

view! {
    Repeat(times = 3, let:index) {
        text {{index.to_string()}}
    }
}

for binds its row name the same way.

Next

On this page