Overlay

Expo UI Overlay matches the official SwiftUI overlay modifier and provides a way to layer secondary content on top of a view, positioned with a specified alignment.

Usage

import { Host, Overlay, Text, Image } from '@expo/ui/swift-ui';
import {
  foregroundStyle,
  frame,
  font,
  background,
  clipShape,
  offset,
} from '@expo/ui/swift-ui/modifiers';

export default function OverlayExample() {
  return (
    <Host
      style={{
        flex: 1,
        justifyContent: 'center',
        alignItems: 'center',
      }}>
      <Overlay alignment="topTrailing">
        <Image
          systemName="bell.fill"
          modifiers={[
            font({ size: 28 }),
            foregroundStyle('#007AFF'),
          ]}
        />
        <Overlay.Content>
          <Text
            modifiers={[
              font({ size: 11, weight: 'bold' }),
              foregroundStyle('#FFFFFF'),
              frame({ width: 18, height: 18 }),
              background('#FF3B30'),
              clipShape('circle'),
              offset({ x: 8, y: -8 }),
            ]}>
            3
          </Text>
        </Overlay.Content>
      </Overlay>
    </Host>
  );
}

A blue bell icon with a red circular badge showing 3 at its top-trailing corner

API

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

Component

`Overlay`

Type: React.Element<OverlayProps>

OverlayProps

`alignment`

Optional • Type: Alignment • Default: 'center'

The alignment of the overlay content relative to the base content.

`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 Overlay, but not all of them do something here.

75 change what you see on Overlay.
1 have no visible effect on Overlay.
13 work only in one place, such as a widget or a Grid.

Best modifiers for Overlay

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

Also works on Overlay

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

No visible effect on Overlay

Overlay accepts these modifiers, but you see no change. They do not give an error.

Modifier	Why nothing happens
`layoutPriority`	It has an effect only when the view shares an axis with other views in a stack.

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:

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

On this page