Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt

Use this file to discover all available pages before exploring further.

Stacks are the primary layout primitives in BindJS. VStack, HStack, and ZStack arrange children vertically, horizontally, or as overlaid layers. LazyVStack and LazyHStack are virtualized variants for long scrollable lists. Group and Section add no layout of their own — they let you apply modifiers across multiple components or attach a header and footer for use inside List. Every stack accepts either (children) or (props, children). Alignment types differ by axis: VStack and LazyVStack use HorizontalAlignment, HStack and LazyHStack use VerticalAlignment, and ZStack uses Alignment.

​
VStack

Arranges children in a vertical line from top to bottom. 
VStack(children: Component): Component;
VStack(children: Component[]): Component;
VStack(props: { spacing?: number; alignment?: HorizontalAlignment }, children: Component[]): Component;
​
children
Component | Component[]
required
A single component or array of components to arrange vertically.
​
props
object
Configuration options for the stack layout.
Basic vertical stack 
VStack([
    Text("First"),
    Text("Second"),
    Text("Third")
])
With spacing and alignment 
VStack({ spacing: 16, alignment: "leading" }, [
    Text("Title").font("headline"),
    Text("Subtitle").foregroundStyle(Color("secondary"))
])
Nested layout 
VStack({ spacing: 24 }, [
    HStack({ spacing: 12 }, [
        Image({ systemName: "person.fill" }),
        Text("Profile")
    ]),
    Divider(),
    Text("Welcome back!").font("body")
])
Pushing content with spacers 
VStack([
    Text("Top"),
    Spacer(),
    Text("Bottom")
])
    .frame({ maxHeight: ".infinity" })

​
HStack

Arranges children in a horizontal line from leading to trailing. 
HStack(children: Component): Component;
HStack(children: Component[]): Component;
HStack(props: { spacing?: number; alignment?: VerticalAlignment }, children: Component[]): Component;
​
children
Component | Component[]
required
A single component or array of components to arrange horizontally.
​
props
object
Configuration options for the stack layout.
Basic horizontal stack 
HStack([
    Image({ systemName: "star.fill" }),
    Text("Favorites")
])
Avatar row with vertical alignment 
HStack({ spacing: 12, alignment: "top" }, [
    Image({ url: "avatar.jpg" })
        .frame({ width: 48, height: 48 })
        .clipShape(Circle()),
    VStack({ alignment: "leading" }, [
        Text("Jane Doe").font("headline"),
        Text("Online").foregroundStyle(Color("green"))
    ])
])
Pushing edges apart 
HStack([
    Text("Leading"),
    Spacer(),
    Text("Trailing")
])
    .padding(16)
Baseline alignment 
HStack({ alignment: "firstTextBaseline" }, [
    Text("Title").font("title"),
    Text("subtitle").font("caption")
])

​
ZStack

Layers children on top of each other in a back-to-front stack. The last child in the array renders on top. 
ZStack(children: Component): Component;
ZStack(children: Component[]): Component;
ZStack(props: { alignment?: Alignment }, children: Component[]): Component;
​
children
Component | Component[]
required
A single component or array of components to layer. The last child renders on top.
​
props
object
Configuration options for the stack.
Basic overlay 
ZStack([
    Image({ url: "background.jpg" }),
    Text("Overlay text")
        .foregroundStyle(Color("white"))
        .font("title")
])
Caption with corner alignment 
ZStack({ alignment: "bottomTrailing" }, [
    Image({ url: "photo.jpg" })
        .frame({ width: 200, height: 200 }),
    Text("Caption")
        .padding(8)
        .background(Color("black").opacity(0.6))
        .foregroundStyle(Color("white"))
        .cornerRadius(4)
])
Notification badge 
ZStack({ alignment: "topTrailing" }, [
    Image({ systemName: "bell" })
        .font("title"),
    Circle()
        .fill(Color("red"))
        .frame({ width: 12, height: 12 })
])
Layered backgrounds 
ZStack([
    Rectangle().fill(Color("blue")),
    Circle()
        .fill(Color("white").opacity(0.3))
        .frame({ width: 150, height: 150 }),
    Text("Center")
        .foregroundStyle(Color("white"))
])
    .frame({ width: 200, height: 200 })

​
LazyVStack

A vertical stack that renders only the children currently visible on screen. Use inside a ScrollView for efficient rendering of long lists. 
LazyVStack(children: Component): Component;
LazyVStack(children: Component[]): Component;
LazyVStack(props: { spacing?: number; alignment?: HorizontalAlignment; pinnedViews?: PinnedScrollableViews }, children: Component[]): Component;
​
children
Component | Component[]
required
A single component or array of components to arrange vertically with lazy rendering.
​
props
object
Configuration options for the lazy stack.
Basic lazy list 
ScrollView([
    LazyVStack({ spacing: 8 }, [
        ForEach(items, (item) =>
            Text(item.name).padding(12)
        )
    ])
])
Pinned section headers 
ScrollView([
    LazyVStack({ pinnedViews: "sectionHeaders" }, [
        Section({ header: Text("Group A").font("headline") }, [
            ForEach(groupA, (item) => Text(item.name))
        ]),
        Section({ header: Text("Group B").font("headline") }, [
            ForEach(groupB, (item) => Text(item.name))
        ])
    ])
])
Leading-aligned message list 
ScrollView([
    LazyVStack({ spacing: 12, alignment: "leading" }, [
        ForEach(messages, (msg) =>
            Text(msg.text)
                .padding(12)
                .background(Color("secondarySystemBackground"))
                .cornerRadius(8)
        )
    ])
])
LazyVStack only creates views for children currently in the viewport. Always place it inside a ScrollView — without a scrollable parent there is no viewport boundary to drive the lazy rendering. For static lists, use VStack.

​
LazyHStack

A horizontal stack that renders only the children currently visible on screen. Use inside a horizontal ScrollView. 
LazyHStack(children: Component): Component;
LazyHStack(children: Component[]): Component;
LazyHStack(props: { spacing?: number; alignment?: VerticalAlignment; pinnedViews?: PinnedScrollableViews }, children: Component[]): Component;
​
children
Component | Component[]
required
A single component or array of components to arrange horizontally with lazy rendering.
​
props
object
Configuration options for the lazy stack.
Horizontal carousel 
ScrollView({ axis: "horizontal", showsIndicators: false }, [
    LazyHStack({ spacing: 16 }, [
        ForEach(cards, (card) =>
            VStack([
                Image({ url: card.imageUrl })
                    .frame({ width: 200, height: 150 })
                    .cornerRadius(12),
                Text(card.title).font("caption")
            ])
        )
    ])
])
Top-aligned cards 
ScrollView({ axis: "horizontal" }, [
    LazyHStack({ spacing: 8, alignment: "top" }, [
        ForEach(items, (item) =>
            VStack({ alignment: "leading" }, [
                Text(item.title).font("headline"),
                Text(item.subtitle).font("subheadline")
            ])
                .frame({ width: 120 })
        )
    ])
])
LazyHStack only creates views for children currently in the viewport. Always place it inside a horizontal ScrollView. For static rows, use HStack.

​
Group

Groups multiple components without adding any layout. Modifiers applied to a Group propagate to each child. A subviews overload lets you decompose an existing component tree and rearrange its children. 
Group(children: Component): Group;
Group(children: Component[]): Group;
Group(subviews: Component, transform: (subviews: Component[]) => Component): Group;
​
children
Component | Component[]
required
A single component or array of components to group together.
​
subviews
Component
required
Subviews overload: a component whose children are decomposed into an array of subviews.
​
transform
(subviews: Component[]) => Component
required
Subviews overload: a function that receives the subviews array and returns a new component layout.
Basic grouping 
Group([
    Text("First"),
    Text("Second"),
    Text("Third")
])
Apply a modifier to multiple children 
Group([
    Text("Red text"),
    Text("Also red")
])
    .foregroundStyle(Color("red"))
Conditional rendering 
const body = () => {
    const [showDetails, setShowDetails] = useState(false)

    return Group(
        showDetails
            ? [Text("Name"), Text("Email")]
            : [Text("Sign in to view")]
    )
}
Subview decomposition 
Group(
    VStack([Text("A"), Text("B"), Text("C")]),
    (subviews) =>
        HStack([subviews[0], Spacer(), subviews[1]])
)
Group adds no layout semantics. Children render according to the parent container’s layout rules. The subviews overload enables view decomposition — inspecting and rearranging children of an existing component tree.

​
Section

Groups content with an optional header and footer. Used inside List, Form, or LazyVStack with pinnedViews. 
Section(children: Component): Component;
Section(children: Component[]): Component;
Section(props: { header?: Component; footer?: Component }, children: Component[]): Component;
​
children
Component | Component[]
required
The content of the section.
​
props
object
Configuration options for the section.
Basic section 
Section([
    Text("Item 1"),
    Text("Item 2"),
    Text("Item 3")
])
Section with header 
Section({ header: Text("Settings") }, [
    Toggle({ label: "Dark Mode", isOn, setIsOn }),
    Toggle({ label: "Notifications", isOn: notifs, setIsOn: setNotifs })
])
Header and footer 
Section(
    {
        header: Text("Account"),
        footer: Text("Your email is used for sign-in.")
    },
    [
        Text("user@example.com"),
        Text("Change password")
    ]
)
Section inside a List 
List([
    Section({ header: Text("Fruits") }, [
        ForEach(fruits, (fruit) => Text(fruit))
    ]),
    Section({ header: Text("Vegetables") }, [
        ForEach(veggies, (veg) => Text(veg))
    ])
])
Sticky headers in a LazyVStack 
ScrollView([
    LazyVStack({ pinnedViews: "sectionHeaders" }, [
        Section({ header: Text("Section A").font("headline") }, [
            ForEach(sectionAItems, (item) => Text(item.name))
        ])
    ])
])

​
See also

  • ScrollView — scrollable container for lazy stacks
  • List — scrollable list with native row chrome
  • ForEach — iterate over data to produce children
  • Spacer — flexible space inside stacks
  • Alignment — alignment values for ZStack and corner-aligned overlays