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.
| Method | What 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()}}
}
}
}
}| Method | What 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:
- The slot child carries the
slotattribute:CardHeader(slot) { … }. - It fills the prop named after its type in snake case:
CardHeaderfillscard_header. To fill a prop with a different name, writeCardHeader(slot = "header"). - 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.