Skip to content

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 ​

UILayoutGuide()

Creates a layout guide. Add it to a view with the view's addLayoutGuide() before using it.

Instance properties ​

PropertyDescription
owningView read-onlyThe view it has been added to
layoutFrame read-onlyThe rectangle computed by layout, in the coordinate system of owningView
identifierA 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:

PropertyDescription
leadingAnchor read-onlyLeading edge
trailingAnchor read-onlyTrailing edge
leftAnchor read-onlyLeft edge
rightAnchor read-onlyRight edge
centerXAnchor read-onlyHorizontal center line
topAnchor read-onlyTop edge
bottomAnchor read-onlyBottom edge
centerYAnchor read-onlyVertical center line
widthAnchor read-onlyWidth
heightAnchor read-onlyHeight

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:

PropertyArea it represents
view.safeAreaLayoutGuideThe 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.layoutMarginsGuideThe 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.readableContentGuideA width suited to reading long text. When the view is very wide, it is narrower than the view
view.keyboardLayoutGuideThe area the keyboard occupies. See UIKeyboardLayoutGuide
scrollView.contentLayoutGuide, frameLayoutGuideThe 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 ​

js
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 ​

ObjCJS
[[UILayoutGuide alloc] init]new UILayoutGuide()
[view addLayoutGuide:guide]view.addLayoutGuide(guide)
view.safeAreaLayoutGuideview.safeAreaLayoutGuide
guide.layoutFrameguide.layoutFrame

See also ​