UILayoutGuide
UILayoutGuide represents a rectangle that takes part in layout but isn't displayed, called a layout guide. It has the same anchors as a view and can be used to create constraints, but it is not a view: it has no background color, doesn't receive touches, and doesn't appear in subviews.
Layout guides are for spacing, grouping, and alignment. When you need a rectangle that only takes part in layout, use one instead of a transparent UIView. The system also provides several ready-made layout guides, such as view.safeAreaLayoutGuide for the safe area.
Inheritance: EventTarget → NSObject → UILayoutGuide
Subclass: UIKeyboardLayoutGuide (with UITrackingLayoutGuide in between, a layer that has no members of its own).
For usage, see the guide Laying out with constraints.
Constructor
Creates a layout guide. Add it to a view with the view's addLayoutGuide() before using it.
Instance properties
| Property | Description |
|---|---|
owningView read-only | The view it has been added to |
layoutFrame read-only | The rectangle computed by layout, in the coordinate system of owningView |
identifier | A name for identifying it when debugging |
10 anchors, with the same meanings as the anchors of the same names on a view. It has two fewer than a view, the baseline anchors, because it has no text:
| Property | Description |
|---|---|
leadingAnchor read-only | Leading edge |
trailingAnchor read-only | Trailing edge |
leftAnchor read-only | Left edge |
rightAnchor read-only | Right edge |
centerXAnchor read-only | Horizontal center line |
topAnchor read-only | Top edge |
bottomAnchor read-only | Bottom edge |
centerYAnchor read-only | Vertical center line |
widthAnchor read-only | Width |
heightAnchor read-only | Height |
Events
UILayoutGuide fires no events. There is no notification when layoutFrame changes; when you need it, read it after layoutIfNeeded().
Concepts
A layout guide is a rectangle that takes part in layout but isn't displayed. It has the same anchors as a view, and constraints can be created with it. It is not a view: it has no background color, doesn't receive touches, and doesn't appear in subviews.
Layout guides the system provides
Read them from properties of a view:
| Property | Area it represents |
|---|---|
view.safeAreaLayoutGuide | The safe area: the part of the view not covered by the notch, the status bar, the rounded screen corners, or the home indicator at the bottom |
view.layoutMarginsGuide | The area inset from each edge of the view by its layout margins. The margins default to 8 pt on each side and can be changed |
view.readableContentGuide | A width suited to reading long text. When the view is very wide, it is narrower than the view |
view.keyboardLayoutGuide | The area the keyboard occupies. See UIKeyboardLayoutGuide |
scrollView.contentLayoutGuide, frameLayoutGuide | The content area and visible area of a scroll view. See UIScrollView |
The exact extents of layoutMarginsGuide and readableContentGuide are not verified in the simulator.
Layout guides you create
Create one with new UILayoutGuide(), then add it to a view with view.addLayoutGuide(). Only after it is added can constraints be created with it. For an example, see Using an invisible rectangle as a placeholder. Common uses:
- Spacing: represent a gap, and make several gaps equal.
- Grouping: enclose several views in one rectangle, then center that rectangle as a whole.
A layout guide's size and position must also be determined by constraints. After layout, read its rectangle from layoutFrame.
Examples
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
// An invisible rectangle filling the top half of the safe area
const top = new UILayoutGuide();
page.view.addLayoutGuide(top);
const safe = page.view.safeAreaLayoutGuide;
NSLayoutConstraint.activateConstraints([
top.topAnchor.constraintEqualToAnchor(safe.topAnchor),
top.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor),
top.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor),
top.heightAnchor.constraintEqualToAnchor(safe.heightAnchor, { multiplier: 0.5 }),
]);
// A square centered in that rectangle
const box = new UIView();
box.backgroundColor = 'systemOrange';
box.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(box);
NSLayoutConstraint.activateConstraints([
box.centerXAnchor.constraintEqualToAnchor(top.centerXAnchor),
box.centerYAnchor.constraintEqualToAnchor(top.centerYAnchor),
box.widthAnchor.constraintEqualToConstant(80),
box.heightAnchor.constraintEqualToConstant(80),
]);
});Effect: an 80 × 80 pt orange square, centered in the top half of the safe area. The layout guide itself is invisible. This code is not verified in the simulator.
Corresponding iOS API
| ObjC | JS |
|---|---|
[[UILayoutGuide alloc] init] | new UILayoutGuide() |
[view addLayoutGuide:guide] | view.addLayoutGuide(guide) |
view.safeAreaLayoutGuide | view.safeAreaLayoutGuide |
guide.layoutFrame | guide.layoutFrame |
See also
NSLayoutConstraintUIView:addLayoutGuide(),removeLayoutGuide(),layoutGuides, and the layout guides the system providesUIKeyboardLayoutGuideUIScrollView:contentLayoutGuide,frameLayoutGuide