ZStack

Expo UI ZStack matches the official SwiftUI ZStack API and overlays its children on top of each other.

Usage

Basic overlapping stack

import { Host, ZStack, Rectangle, Text } from '@expo/ui/swift-ui';
import {
  frame,
  foregroundStyle,
} from '@expo/ui/swift-ui/modifiers';

export default function BasicZStackExample() {
  return (
    <Host style={{ flex: 1 }}>
      <ZStack>
        <Rectangle
          modifiers={[
            frame({ width: 100, height: 100 }),
            foregroundStyle('blue'),
          ]}
        />
        <Text modifiers={[foregroundStyle('white')]}>Overlay</Text>
      </ZStack>
    </Host>
  );
}

A blue square with the white word Overlay centered on top of it

The alignment prop controls how children are positioned within the stack. Available options include: center, leading, trailing, top, bottom, topLeading, topTrailing, bottomLeading, and bottomTrailing.

import { Host, ZStack, Rectangle, Circle } from '@expo/ui/swift-ui';
import {
  frame,
  foregroundStyle,
} from '@expo/ui/swift-ui/modifiers';

export default function ZStackAlignmentExample() {
  return (
    <Host style={{ flex: 1 }}>
      <ZStack alignment="bottomTrailing">
        <Rectangle
          modifiers={[
            frame({ width: 100, height: 100 }),
            foregroundStyle('blue'),
          ]}
        />
        <Circle
          modifiers={[
            frame({ width: 30, height: 30 }),
            foregroundStyle('red'),
          ]}
        />
      </ZStack>
    </Host>
  );
}

A blue square with a small red circle at its bottom trailing corner

Creating a badge overlay

import {
  Host,
  ZStack,
  Circle,
  Text,
  Image,
} from '@expo/ui/swift-ui';
import {
  frame,
  foregroundStyle,
} from '@expo/ui/swift-ui/modifiers';

export default function ZStackBadgeExample() {
  return (
    <Host style={{ flex: 1 }}>
      <ZStack alignment="topTrailing">
        <Image systemName="bell.fill" size={32} color="blue" />
        <Circle
          modifiers={[
            frame({ width: 16, height: 16 }),
            foregroundStyle('red'),
          ]}
        />
      </ZStack>
    </Host>
  );
}

API

import { ZStack } from '@expo/ui/swift-ui';

Component

`ZStack`

Type: React.Element<ZStackProps>

ZStackProps

`alignment`

Optional • Type: Alignment

The alignment of children within the stack.

`children`

Type: ReactNode

Inherited props

CommonViewModifierProps

Modifiers

Use these modifiers in the modifiers prop of the SwiftUI version.

Expo UI lets you put any of the 89 modifiers for any view on ZStack, but not all of them do something here.

76 change what you see on ZStack.
2 work, but not in the way that you may expect.
13 work only in one place, such as a widget or a Grid.

Best modifiers for ZStack

These modifiers are the ones that you use most with ZStack.

Also works on ZStack

ZStack takes these modifiers too, and each one works in the usual way.

Needs care on ZStack

These modifiers work on ZStack, but not in the way that you may expect.

Modifier	What to know
`onLongPressGesture`	Touches on the empty space between children are not detected. Add `contentShape('rectangle')` before this modifier.
`onTapGesture`	Touches on the empty space between children are not detected. Add `contentShape('rectangle')` before this modifier.

Only in some places

These modifiers work only in a widget, in a Grid, in a Namespace or in a parent that asks for them.

Modifier	Where it works
`activityBackgroundTint`	Works only in a Live Activity. It has no effect in the app.
`alignmentGuide`	Has an effect only when the parent, such as a `VStack` or `ZStack`, aligns its children by the same guide.
`containerBackground`	Works only in a widget, or in a navigation container when you use a `navigation` placement.
`glassEffectId`	Works only on a view that also has `glassEffect`, in a `GlassEffectContainer` and a `Namespace`.
`gridCellAnchor` iOS 16+	Works only on a cell of a `Grid`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridCellColumns`	Works only on a view in a `Grid.Row`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridCellUnsizedAxes`	Works only on a view in a `Grid`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`gridColumnAlignment` iOS 16+	Works only on a view in a `Grid.Row`. `Grid` is in `@expo/ui/swift-ui`, but it has no Expo docs page.
`invalidatableContent` iOS 17+	Has an effect only when a parent view uses `redacted` with the `invalidated` reason.
`matchedGeometryEffect`	Works only in a `Namespace`. Give two views the same `id` and change between them with an animation.
`privacySensitive`	Has an effect only when a parent view uses `redacted` with the `privacy` reason.
`unredacted`	Has an effect only in a parent view that uses `redacted`.
`widgetURL`	Works only in a widget. It has no effect in the app.

Sources

The original Expo docs for this page:

ZStack (SwiftUI) (source-of-truth/versions/v57.0.0/sdk/ui/swift-ui/zstack.md)