# UIOverlayArrangement An arrangement that layers the primary view over the secondary view, or places the views side by side on a folded display. ``` @interface UIOverlayArrangement : UIArrangement ``` ## Overview An overlay arrangement view controller places a primary view controller and a secondary view controller in a stacked arrangement when the device has a flat display, or next to each other horizontally when someone is holding a folded device in landscape orientation or above and below each other when someone is holding a folded device in portrait orientation. Here’s how the overlay arrangement positions the primary and secondary views: - In a stacked overlay arrangement, the arrangement places the primary view above the secondary view in the z-axis. - When someone holds a folded iPhone Duo in portrait orientation, the arrangement places the secondary view in the top position and the primary view in the bottom position. - When someone holds a folded iPhone Duo in landscape orientation, the arrangement places the secondary view in the leading position and the primary view in the trailing position. **Portrait open:**  **Portrait folded:**  **Landscape open:**  **Landscape folded:**  Create an overlay arrangement view controller by specifying a primary and secondary view controller, and call the [`updateArrangement:`](/documentation/UIKit/UIArrangementViewController/updateArrangement:) method with [`overlayArrangement`](/documentation/UIKit/UIOverlayArrangement-c.class/overlayArrangement): ```objc self.arrangementVC = [[UIArrangementViewController alloc] init]; self.primaryVC = [[PrimaryController alloc] init]; [self.arrangementVC setViewController:self.primaryVC forPlacement:UIArrangementViewControllerViewPlacementPrimary]; self.secondaryVC = [[SecondaryController alloc] init]; [self.arrangementVC setViewController:self.secondaryVC forPlacement:UIArrangementViewControllerViewPlacementSecondary]; UIOverlayArrangement *arrangement = [UIOverlayArrangement overlayArrangement]; [self.arrangementVC updateArrangement:arrangement]; ``` ### Limit an overlay arrangement by orientation You can limit which axes your overlay arrangement view controller supports by specifying the axes for the arrangement. The following example shows an arrangement that only splits vertically: ```objc self.arrangementVC = [[UIArrangementViewController alloc] init]; self.primaryVC = [[PrimaryController alloc] init]; [self.arrangementVC setViewController:self.primaryVC forPlacement:UIArrangementViewControllerViewPlacementPrimary]; self.secondaryVC = [[SecondaryController alloc] init]; [self.arrangementVC setViewController:self.secondaryVC forPlacement:UIArrangementViewControllerViewPlacementSecondary]; UIOverlayArrangement *arrangement = [UIOverlayArrangement overlayArrangement]; arrangement.axes = UIAxisVertical; [self.arrangementVC updateArrangement:arrangement]; ``` Use [`axes`](/documentation/UIKit/UIOverlayArrangement-c.class/axes) to set the axes for an overlay arrangement. For axes that you don’t include, the arrangement view only displays the primary view. ### Customize a folded layout You can adjust how the overlay arrangement positions the primary and secondary views on a folded iPhone Duo with view properties. For example, if you would prefer the primary view to appear in the leading position instead of the trailing position when someone holds a folded iPhone Duo in landscape orientation, customize the overlay arrangement with view properties. Start by creating a [`UIOverlayArrangement`](/documentation/UIKit/UIOverlayArrangement-c.class) instance and a [`UIOverlayArrangementViewProperties`](/documentation/UIKit/UIOverlayArrangementViewProperties) instance: ```objc UIOverlayArrangement *overlayArrangement = [UIOverlayArrangement overlayArrangement]; UIOverlayArrangementViewProperties *primaryViewProperties = [overlayArrangement.defaultViewProperties copy]; ``` Specify an edge for the [`edge`](/documentation/UIKit/UIOverlayArrangementViewProperties/edge) property, and then update the overlay arrangement and arrangement view controller: ```objc primaryViewProperties.edge = NSDirectionalRectEdgeLeading; [overlayArrangement setViewProperties:primaryViewProperties forPlacement:UIArrangementViewControllerViewPlacementPrimary]; [arrangementViewController updateArrangement:overlayArrangement animated:NO]; ``` ## Topics ### Creating an overlay arrangement [`+ (instancetype) overlayArrangement;`](/documentation/UIKit/UIOverlayArrangement-c.class/overlayArrangement) Returns an overlay arrangement. ### Configuring the arrangement [`@property (nonatomic) UIAxis axes;`](/documentation/UIKit/UIOverlayArrangement-c.class/axes) The supported axes of the arrangement. [`@property (nonatomic, copy, readonly) UIOverlayArrangementViewProperties * defaultViewProperties;`](/documentation/UIKit/UIOverlayArrangement-c.class/defaultViewProperties) Returns the default properties for a view in the overlay arrangement. [`- (void) setViewProperties:(UIOverlayArrangementViewProperties *) viewProperties forPlacement:(UIArrangementViewControllerViewPlacement) placement;`](/documentation/UIKit/UIOverlayArrangement-c.class/setViewProperties:forPlacement:) Sets the view properties in the overlay arrangement for a specific placement. [`@interface UIOverlayArrangementViewProperties : NSObject`](/documentation/UIKit/UIOverlayArrangementViewProperties) Properties you use to customize how an overlay arrangement presents a view. ## Relationships ### Inherits From [`UIArrangement`](/documentation/UIKit/UIArrangement) --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)