ArrangementView for iPhone Duo

What ArrangementView is

ArrangementView is a SwiftUI container introduced with iOS 27.1: you hand it two related regions — primary and secondary — and the system chooses how they share the area as the window resizes or the device folds.

It is not a new layout engine you implement yourself. You are not replacing Layout or AnyLayout. You describe a relationship; presentation is the system's job. The UIKit counterpart is UIArrangementViewController.

ArrangementView {
    PlayerView()
} secondary: {
    TranscriptView()
}
.arrangementViewStyle(.split)

Split style

.split is the default: it divides the available area so both children stay independently visible — horizontal when the container is wider than it is tall, vertical when it is taller than it is wide.

Restrict the axis when only one direction is useful. If the preferred axis cannot be honored — a narrow Split View pane, for example — the system may show only one of the two views instead of forcing a cramped split.

ArrangementView {
    CanvasView()
} secondary: {
    InspectorView()
}
.arrangementViewStyle(.split.axes(.horizontal))

Overlay style

.overlay treats children as foreground and background: they can stack, then sit side by side when geometry changes — use it when one region may sit above the other rather than claiming a permanent column.

ArrangementView {
    VideoSurface()
} secondary: {
    PlaybackChrome()
}
.arrangementViewStyle(.overlay)

Overlay z-index

Read @Environment(\.overlayArrangementZIndex) in the overlay child — a zIndex greater than 0 means that child is in front and should use its compact or collapsed presentation. Do not infer front/back from device model or a hardcoded fold angle.

struct PlaybackChrome: View {
    @Environment(\.overlayArrangementZIndex) private var zIndex

    var body: some View {
        if zIndex > 0 {
            CompactControls()
        } else {
            ExpandedControls()
        }
    }
}

Split vs overlay

Choose the style from the relationship, not from the hardware. Split keeps both regions independently on screen. Overlay lets one sit above the other and collapse when it is in front.

• If the natural sketch is an HStack or VStack, start with .split.
• If the natural sketch is a ZStack, start with .overlay.
• Keep list-detail navigation in NavigationSplitView; use ArrangementView for two content regions that should move together.

You can still use size classes and geometry for the rest of the app. ArrangementView is the piece that owns the two regions whose placement should change with Duo's fold and window size.

Placement rules

Put ArrangementView inside a NavigationStack as a major-region container — not inside a List, ScrollView, or NavigationSplitView. Those parents already own scrolling and column collapsing, and they will clip or ignore the arrangement.

NavigationStack {
    ArrangementView {
        PlayerView()
    } secondary: {
        TranscriptView()
    }
    .arrangementViewStyle(.split)
    .navigationTitle("Session")
}

Frequently asked questions