Technical

SwiftUI’s ArrangementView Makes Adaptive Two-Pane Layout a Framework Decision

The iOS 27.1 container expresses split and overlay relationships across changing geometry; its ratio remains a preference, and a reported Duo simulator bug calls for a targeted test.

6 min read2026-09-24

ArrangementView turns geometry into a two-view decision

SwiftUI’s ArrangementView is a container for a relationship, not a second spelling of HStack. Apple describes an arrangement as a mapping from inputs such as size classes, a view’s aspect ratio, and active division regions to outputs such as whether a view appears and the frame it receives. In iOS 27.1, SwiftUI exposes system-provided arrangements to apps.¹²

That definition matters on devices whose usable space changes without the app changing its content. A hinge can create a division region, a fold can turn a wide area into two regions, and a tall aspect ratio can make a horizontal split unsuitable. ArrangementView takes one primary and one secondary view, then applies a selected style to the current bounds.¹³

This is narrower than responsive layout in general. It fits an interface that already says, “this is the main experience, and this is the companion view.” When the composition has arbitrary panels or independent placement rules, the app still has a case for an ordinary stack, a custom Layout, or a grid.

The primary and secondary closures carry the design

Apple’s Tech Talk demonstrates an audio-note player with an Up Next panel. The smallest SwiftUI version is a container with two closures and an explicit split style:

PlayerAndUpNext.swift · illustrativeswift

struct PlayerAndUpNext: View {
    var body: some View {
        NavigationStack {
            ArrangementView {
                PlayerView()
            } secondary: {
                UpNextView()
            }
            .arrangementViewStyle(.split)
        }
    }
}

The documented SwiftUI shape for a player as primary content and an Up Next panel as secondary content.¹³

The first closure is the primary view; the trailing secondary closure is its companion. .arrangementViewStyle(.split) makes the choice explicit even though split is the default style. The container owns the two-view relationship and receives the bounds to arrange. The child views do not need to calculate a pane width just to participate in that relationship.¹

The relationship stays the same while the framework changes placement. On a wide rectangle, the views can share a row. On a taller rectangle, the default split can run vertically. The useful unit is therefore primary content plus secondary content with a placement rule, rather than a list of width thresholds copied into each screen.¹

Split keeps both views visible; overlay gives one view the foreground

A split arrangement divides its provided bounds between the two views. By default it splits horizontally when the container is wider than it is tall, and vertically when it is taller than it is wide. An app can restrict the style to one axis. If that axis is unavailable for the current bounds, the arrangement falls back to showing only the primary view.¹⁴

HorizontalPlayerAndUpNext.swift · illustrativeswift

struct HorizontalPlayerAndUpNext: View {
    var body: some View {
        ArrangementView {
            PlayerView()
        } secondary: {
            UpNextView()
        }
        .arrangementViewStyle(.split.axes(.horizontal))
    }
}

Restricting split to the horizontal axis makes the single-view fallback relevant when the container is taller than it is wide.¹⁴

Overlay encodes a different relationship. It prefers to place the two views above or below one another, and it can prefer side-by-side placement when a device folds. Apple maps overlay to a foreground/background relationship, such as controls over readable content, where partial obscuring is acceptable. A main-detail pair whose views must remain visible is the split case.¹⁵

OverlayUpNextView.swift · illustrativeswift

enum UpNextMinimization {
    case collapsed
    case expanded
}

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

    var body: some View {
        UpNextList(minimization: minimization)
    }

    private var minimization: UpNextMinimization {
        zIndex > 0 ? .collapsed : .expanded
    }
}

struct OverlayPlayer: View {
    var body: some View {
        ArrangementView {
            OverlayUpNextView()
        } secondary: {
            PlayerView()
        }
        .arrangementViewStyle(.overlay)
    }
}

Overlay content can read overlayArrangementZIndex and switch its presentation as the framework changes which view is in front. UpNextList is an app-owned view.¹⁵

The environment value reports placement; it is not a general z-order control. The Tech Talk uses the sign of that value to choose a collapsed or expanded Up Next representation as the device folds and unfolds. That lets the secondary view adapt its content when its visual relationship changes, instead of merely shrinking the same view until it is unusable.¹

The ratio asks for a proportion, then yields to geometry

splitArrangementLayoutRatio(0.3) is useful because it expresses intent without pretending to be a measurement. Applied to the primary child, it asks for a preferred size ratio in the split arrangement. It does not set a fixed pixel width, and it does not guarantee that the primary view will occupy exactly 30 percent in every configuration.⁶

RatioControlledPlayer.swift · illustrativeswift

struct RatioControlledPlayer: View {
    var body: some View {
        ArrangementView {
            PlayerView()
                .splitArrangementLayoutRatio(0.3)
        } secondary: {
            UpNextView()
        }
        .arrangementViewStyle(.split)
    }
}

The ratio modifier belongs on the arranged child whose preferred share is being expressed; it is a layout preference rather than a frame constraint.⁶

That distinction changes how the layout should be tested. A value of 0.3 describes the preferred result when split has room. The arrangement may not honor that preference when the available aspect ratio, an active division region, or the selected axis cannot support it. Replacing the modifier with frame(width:) would trade the framework’s geometry decision for a number that describes only one size of window.¹⁶

Apple treats a fold or hinge as a reserved region that can divide a larger area into usable regions. SwiftUI exposes those regions through geometry APIs, and the Tech Talk describes the division region as active when the Duo is folded and inactive when it is flat. That gives an implementation a practical test matrix: wide and tall bounds, the restricted-axis fallback, folded and unfolded division regions, and both overlay z-index states.¹⁷

Test the fold before choosing the abstraction

The new geometry needs a concrete test boundary. In a September 24, 2026 Apple Developer Forums report, an ArrangementView overlay implementation received a distinct overlayArrangementZIndex on other iPhone simulators but not on the Duo simulator. Apple’s developer support response identified the behavior as a known bug, said the expected condition is zIndex > 0, and suggested wrapping the controls in a VStack in the primary closure as a workaround.⁸⁹

DuoOverlayWorkaround.swift · reported shapeswift

struct DuoOverlayWorkaround: View {
    var body: some View {
        ArrangementView {
            VStack {
                Controls()
            }
        } secondary: {
            PlayerView()
        }
        .arrangementViewStyle(.overlay)
    }
}

The forum report’s workaround shape wraps the overlay controls in VStack inside the primary closure. Controls and PlayerView stand for app-owned views; this is not a benchmark or a universal fix.⁹

Apple also says that an arrangement supplies layout infrastructure, not navigation infrastructure, and cautions against placing navigation containers inside one or placing an arrangement inside scrolling containers. Those boundaries make the choice more concrete: the framework can own a two-view placement decision, while the surrounding screen still owns navigation and scrolling.¹