ArrangementView in SwiftUI: Split vs Overlay on iPhone Duo

Many screens are really two views that belong together: a player and its queue, a conversation and its photos, a podcast and its transcript. On a regular iPhone you stack them. On the inner display of iPhone Duo you want them side by side, and when someone half-folds the device, neither view should sit across the crease. ArrangementView in SwiftUI is Apple's answer to that problem. This guide covers what it does, the two styles, how sizing works around the hinge, and when to reach for NavigationSplitView instead.

ArrangementView, its styles, and the sizing modifiers are listed in Apple's documentation as available in iOS 27.1 and later, and you need Xcode 27.1 to build for the full iPhone Duo experience. These APIs are new, so details may change between releases. Everything below comes from Apple's documentation, the Tech Talk Strike a pose with adaptive layouts on iPhone Duo, and posts by iOS developer Sarun Wongpatcharapakorn (@sarunw). We haven't run this code on hardware ourselves.

What is ArrangementView in SwiftUI?

ArrangementView is a container that holds exactly two views, a primary and a secondary, and lays them out for you. In the Tech Talk, Apple describes arrangements as a new layer that sits between navigation containers and content containers.

The rules that drive an arrangement read three inputs: the horizontal and vertical size class of the view, its aspect ratio, and whether any division regions are active. On iPhone Duo, the division region is the fold. From those inputs, the arrangement decides whether each view appears and what frame it gets. That's the key difference from an HStack or VStack: a stack always shows every child, but an arrangement may hide the secondary view when there isn't room. An Apple engineer confirmed on the developer forums that this collapse is expected behavior.

UIKit has the same concept in UIArrangementViewController, which takes a primary and a secondary view controller. This post focuses on SwiftUI.

How do I add an ArrangementView to my app?

You create an arrangement with two trailing closures and place it inside a navigation container. This is the shape Apple uses in the Tech Talk:

var body: some View {
    NavigationStack {
        ArrangementView {
            PlayerView()
        } secondary: {
            UpNextView()
        }
    }
}

The first closure is the primary view, and the secondary: closure is the secondary one. Sarun's diagrams call these "First View" and "Secondary View," which is the same thing.

Placement matters. ArrangementView provides no navigation of its own, so navigation goes around it, not inside it. Apple's documentation also says to avoid putting an arrangement inside a scroll view, list, grid, or navigation split view, and to avoid putting a navigation split view or tab view inside an arrangement.

To pick a style, apply arrangementViewStyle(_:). You can also limit the axes an arrangement uses:

ArrangementView {
    NowPlayingView()
} secondary: {
    LyricsView()
}
.arrangementViewStyle(.split.axes(.horizontal))

For any axis you leave out, the arrangement shows only the primary view.

Split vs overlay: which ArrangementView style should I use?

There are two styles. The default style resolves to split, and overlay is the alternative. They behave the same on some poses and very differently on others. The terms below follow the device: closed means you're using the outer display, half-open means partially folded on the inner display, and open means flat.

Sarun sums up split this way: it "will try to put each view side by side," and if there isn't enough space, only the first view shows. Overlay "stacks the two views most of the time," and in a fold the two sit side by side with First View on the right, which is the opposite of split. Apple's documentation describes the same placement: in a folded landscape pose, overlay puts the secondary view leading and the primary view trailing. To flip that, apply overlayArrangementEdge(.leading) to the primary view.

Apple's guidance for choosing is simple. Use split for a main-and-detail relationship where neither view should be covered, like a podcast and its transcript. Use overlay when there's a clear foreground and background, like playback controls over a video. If your current layout is an HStack or VStack, split is the natural match. If it's a ZStack, use overlay.

In an overlay arrangement, a view can read its stacking position and change its presentation. The Tech Talk switches a view to a collapsed form when the value is greater than zero:

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

    var body: some View {
        ControlsPanel(isCollapsed: zIndex > 0)
    }
}

ControlsPanel stands in for your own view.

How does splitArrangementLayoutRatio work on iPhone Duo?

By default, a split arrangement sizes both views equally. To change that, apply splitArrangementLayoutRatio(_:) to one of them. It takes an optional CGFloat between zero and one. This is Apple's example:

ArrangementView {
    ConversationView()
        .splitArrangementLayoutRatio(0.3)
} secondary: {
    PhotosView()
}
.arrangementViewStyle(.split.axes(.horizontal))

The arrangement sizes the view with the highest layoutPriority first, using its ratio. If that ratio asks for more than the remaining space, the view gets the remaining space instead. If the ratios leave space unfilled, the higher-priority view grows to fill it. Apple also documents related modifiers for minimum, ideal, and maximum ratios, explicit sizes with splitArrangementLayoutSize, and splitArrangementFixedLayoutSize.

There's one important exception. Sarun reports that on a half-open iPhone Duo, splitArrangementLayoutRatio is ignored and the split always sits on the hinge, half and half. That makes sense: a 30/70 split would put the edge of one pane across the crease. Design your ratio for the flat display, and expect an even split when the device is folded. We couldn't find this behavior stated in Apple's documentation, so treat it as observed behavior in iOS 27.2.

Even split doesn't mean equal pane sizes. In Sarun's diagram of a half-open device in landscape, each half of the display is 475 points, and the status bar takes 84 points along the right edge. The secondary pane comes out narrower as a result. Always lay out for the size you're given rather than assuming the two panes match.

To learn how the fold itself is reported, see how reserved regions describe the iPhone Duo fold.

What size classes does each ArrangementView pane get?

Each pane in an arrangement gets its own size classes, and they often differ from the window's. Sarun measured them on iOS 27.2. H is horizontal and V is vertical.

Two rules fall out of this. First, the split axis goes compact: side by side gives each pane a compact width, and stacked gives each pane a compact height. Second, on the inner display, half-open or open, panes get the same size classes as an ArrangementView on iPad.

So a pane that sits on a regular-width inner display can still report a compact horizontal size class. Build each pane to respond to its own environment, and don't read the window's traits from inside it. For the window-level values, see iPhone Duo size classes.

You can also read the split direction directly. The splitArrangementAxis environment value is .horizontal or .vertical inside a split arrangement and nil outside one. Apple's example uses it to switch a pane's inner layout:

struct DetailsView: View {
    @Environment(\.splitArrangementAxis) var axis

    var body: some View {
        let layout: AnyLayout = axis == .horizontal
            ? AnyLayout(VStackLayout())
            : AnyLayout(HStackLayout())
        layout {
            Artwork()
            Metadata()
        }
    }
}

When the secondary view is hidden, its controls go with it. On the forums, an Apple engineer suggested giving the essential view a higher layoutPriority so it's the one that survives. You may also want a button or sheet that reaches the secondary content in that state.

ArrangementView vs NavigationSplitView: when should I use each?

They solve different problems, and they aren't meant to nest.

Use NavigationSplitView when the views are levels of navigation, like a list of emails and the selected email. Apple's design guidance says split views expand on the inner display, collapse to a single pane on the outer display, and adjust for the fold on their own. If your app already uses one, you may not need ArrangementView at all.

Use ArrangementView for two views that live on the same screen, inside one destination. A video and its controls, a recipe and its timer, or a game board and its scorecard are all good fits. One pattern from Apple's iPhone Duo design guidance is the tabletop pose: content that benefits from being seen at a distance goes on the upright half, and controls go on the half lying flat. Games such as those on our Built for the Fold page show how strong that layout can be.

In UIKit, the same advice applies to UISplitViewController and UIArrangementViewController. On the forums, an Apple evangelist noted that Apple doesn't recommend embedding a UINavigationController inside a UIArrangementViewController.

Key takeaways

• ArrangementView, new in iOS 27.1, lays out a primary and a secondary view using size classes, aspect ratio, and the fold. Unlike a stack, it can hide the secondary view.
• Split keeps both views in separate spaces and shows only the primary when it can't split. Overlay layers them on a flat display and separates them at the fold, with the primary trailing.
• splitArrangementLayoutRatio shapes the flat layout. On a half-open iPhone Duo, Sarun reports it's ignored and the split sits on the hinge.
• Each pane gets its own size classes, and the split axis goes compact. Read the environment inside each pane.
• Put ArrangementView inside a navigation container, never inside a list, scroll view, or NavigationSplitView.

Next, learn how to react to the hinge itself in iPhone Duo hinge states and onHingeChange, or work through the iPhone Duo app preparation checklist.