/iphone-duo-vertical-bars

name: iphone-duo-vertical-bars
description: Adapt toolbars, navigation bars and tab bars for the vertical axis on iPhone Duo — item ordering, symbol vs text representations, axis behavior, overflow menus, visibility priority, and when to opt out. Use when toolbar items look wrong, overflow too early, or need to move to the side on the outer display.

Bars on the vertical axis

iPhone Duo's displays are wider and shorter than a traditional iPhone's. Vertical space is the scarce resource, so the system moves controls that normally sit at the top and bottom over to the **side**, where they also land closer to the thumb. The content area to their left stays uninterrupted and comparable to a conventional iPhone screen.

Same components, different axis. The position stays consistent as the user opens the device to the inner display in landscape. **The one pose that keeps horizontal bars is the inner display in portrait**, where there is plenty of vertical room for content.

Opting in

Two requirements, both mandatory:

**1. Rebuild against the latest SDK.** Without this the bars stay horizontal.

**2. Use bars that come from navigation containers.** In SwiftUI, pair the `toolbar` modifier with `NavigationStack` or `NavigationSplitView`. In UIKit, prefer `UINavigationController` and `UITabBarController`, which manage their own bars — set toolbar items on a view controller and put it in a navigation controller.

If you build a bar by hand out of `UIToolbar`, `UINavigationBar` or `UITabBar`, its content is **not considered** for vertical layout. This is the single most common reason an app's bars stay stubbornly horizontal.

How items are placed

Navigation, toolbar and tab bar controls all coexist in one shared vertical region. Picture the horizontal bar rotated 90° into a vertical stack — depending on the screen it may hold toolbar items, tab items, or both.

Two structural exceptions:

• **Split views** — only the detail column participates. Items in other columns

stay horizontal.

• **Inspectors** — no vertical bar of their own when expanded, since the detail

column already has one and two would be confusing.

**Sheets** vary by display. On the outer display a sheet that already has a toolbar gets it vertically. On the inner display sheets are centered and their items stay horizontal. When you move a sheet with the preferred-placement API, a sheet placed on the right gets a vertical bar; one placed on the left does not.

The bar is aligned to the **hardware**, so it stays on the same physical side in right-to-left languages. Content adapts around it; the bar itself does not move.

Ordering items

Audit your toolbar configuration against this hierarchy, top to bottom:

1. **Primary navigation** — back, close. With a navigation controller the back button is added for you. For a custom back or close, make a `ToolbarItem` with `cancellationAction` placement in SwiftUI; in UIKit add an item to `leadingItemGroups`. 2. **Prominent actions** — done, and similar. Use the `topBarPinnedTrailing` placement in SwiftUI, `pinnedTrailingGroup` in UIKit. Group related items with `ToolbarItemPlacement` semantics rather than positioning them by hand. 3. **Everything else**, keeping its original grouping. A vertical spacer separates top and bottom placements even once they're unified into one bar.

Not every pose lays bars out vertically, so keep placement consistent. Users should not have to relearn where an action lives each time they open the device.

Symbol or text

This is where most polish is won or lost.

A horizontal bar gives items a fixed height and flexible width. A vertical bar inverts that: **fixed width, flexible height**. Narrow and tall strongly favors **symbol-only** representations.

The system already picks a representation from the icon and title you supply — icon when visible in a bar, text when there is no icon, both once the item moves into an overflow menu. None of that changes. What is new is that the system also weighs whether an item suits the vertical axis: items with an icon go vertical, text-only items stay horizontal.

So: **always provide both a title and an image**, even when you expect the image to be used. Use a SwiftUI `Label` or the corresponding `UIBarButtonItem` properties. The title is what the system falls back on in overflow menus and expanded forms.

Overriding with axis behavior

The inference is usually right. When it isn't, override it: the `.axisBehavior(_:)` modifier taking a `ToolbarItemAxisBehavior` in SwiftUI, or `UIBarButtonItem.axisBehavior` (a `UIBarButtonItem.AxisBehavior`) in UIKit.

**Force horizontal** when an item alternates between a symbol and text — an edit button that becomes "Done", for example. Even though the symbol could sit in a vertical bar, the text form can't, and an item that jumps axes is jarring. The system Edit button handles this already; a custom equivalent needs the horizontal-only behavior. Keep related items on the same axis as a rule.

**Allow vertical** when you have a custom view that the system would otherwise keep horizontal but which does have a good vertical representation.

Reducing text so more can go vertical

Minimize title-only items and custom views that pair text with an image. Most are better as symbols. A count rendered inline next to an icon, for instance, becomes a **badge** on the symbol — the iOS 26 badge API gives you the standard appearance on every device — turning a mixed item into a symbol-only one.

The test: *is the text reinforcing the symbol, or carrying information the symbol can't?* Supplementary text can go. A cart button showing a running total cannot — keep that one horizontal.

Keyboard accessory bars stay attached to the keyboard. They never move to the vertical axis.

Custom views

Opted-in custom views must either fit the bar's fixed width or lay out vertically on their own. Revisit their metrics — a control panel might hide its labels and sh