Layout — Stacks

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.

Show properties

spacing

number

The distance in points between adjacent children. When omitted, the system uses a default spacing.

alignment

HorizontalAlignment

The horizontal alignment of children within the stack. One of "leading", "center", or "trailing". Defaults to "center".

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.

Show properties

spacing

number

The distance in points between adjacent children. When omitted, the system uses a default spacing.

alignment

VerticalAlignment

The vertical alignment of children within the stack. One of "top", "center", "bottom", "firstTextBaseline", or "lastTextBaseline". Defaults to "center".

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.

Show properties

alignment

Alignment

The alignment of children within the stack. See Alignment for all values. Defaults to "center".

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.

Show properties

spacing

number

The distance in points between adjacent children. When omitted, the system uses a default spacing.

alignment

HorizontalAlignment

The horizontal alignment of children within the stack. One of "leading", "center", or "trailing". Defaults to "center".

pinnedViews

PinnedScrollableViews

Which views to pin during scrolling. One of "sectionHeaders", "sectionFooters", or "all". When set, Section headers and footers stick to the edges of the scroll view while their content is visible.

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.

Show properties

spacing

number

The distance in points between adjacent children. When omitted, the system uses a default spacing.

alignment

VerticalAlignment

The vertical alignment of children within the stack. One of "top", "center", "bottom", "firstTextBaseline", or "lastTextBaseline". Defaults to "center".

pinnedViews

PinnedScrollableViews

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.

Show properties

header

Component

A component displayed above the section content. Typically a Text with a headline style.

footer

Component

A component displayed below the section content. Typically a Text with a caption or explanatory note.

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))
        ])
    ])
])

​VStack

​HStack

​ZStack

​LazyVStack

​LazyHStack

​Group

​Section

​See also

VStack

HStack

ZStack

LazyVStack

LazyHStack

Group

Section

See also