`<builder>`

A tag that wraps its children in a builder function.

This tag is useful when the parent requires a builder function, such as PageView.builder. Use vars to define the builder function arguments. When the builder function executes, the values of named arguments defined in vars are stored as dependencies in the current Dependencies instance. The values of placeholder arguments (_) are simply ignored. The BuildContext is never stored as a dependency, even if explicitly named, because it would cause a memory leak.

Attributes

Name	Type	Description	Required	Default
`for`	String	The name of the parent's attribute that will be assigned the builder function. When omitted, the builder is added as a positional child of the parent.	No	`null`
`vars`	String	A comma-separated list of builder function arguments. Named arguments are stored as dependencies. Use `_` to ignore. Supports up to five.	No	`null`
`returnType`	String	Whether the builder returns a single child or a list of children. See Return Types.	No	`null`
`dependenciesScope`	String	How to scope dependencies: `new`, `copy`, or `inherit`. Defaults to `inherit`, or `copy` when `vars` is present.	No	auto

Return Types

The returnType attribute tells the builder whether to return a single child or a list of children. When omitted, the builder returns a single child by default.

Value	Result
(omitted)	Returns a single child
`List`	Returns a list of children
`List:Type`	Returns a typed list, e.g. `List:PopupMenuEntry`

Examples

Basic Builder

<PageView.builder itemCount="3">
    <builder for="itemBuilder" vars="_,index">
        <Container>
            <Text data="${toString(index)}"/>
        </Container>
    </builder>
</PageView.builder>

ListView Builder

<ListView.builder itemCount="${length(items)}">
    <builder for="itemBuilder" vars="_,index">
        <Card>
            <Text data="${items[index].name}"/>
        </Card>
    </builder>
</ListView.builder>

Multi-Child Builder

<PopupMenuButton>
    <builder for="itemBuilder" vars="_" returnType="List">
        <PopupMenuItem value="edit">
            <Text data="Edit"/>
        </PopupMenuItem>
        <PopupMenuItem value="delete">
            <Text data="Delete"/>
        </PopupMenuItem>
    </builder>
</PopupMenuButton>

LayoutBuilder

<LayoutBuilder>
    <builder for="builder" vars="_,constraints">
        <Text data="Constraints: ${toString(constraints)}"/>
    </builder>
</LayoutBuilder>

Custom Builder Types

The <builder> tag works with any widget that uses a typed builder callback, including third-party widgets with custom return types.

<SideMenu>
    <builder for="builder" vars="data">
        <SideMenuData>
            <!-- menu content -->
        </SideMenuData>
    </builder>
</SideMenu>

<builder>