Layout
A type that defines the geometry of a collection of views.
Declaration
type Layout = GridLayout | HStackLayout | VStackLayout | ZStackLayout;@preconcurrency protocol Layout : Sendable, AnimatableOverview
You traditionally arrange views in your app's user interface using built-in
layout containers like HStack and Grid. If you need more complex
layout behavior, you can define a custom layout container by creating a type
that conforms to the Layout protocol and implementing its required
methods:
Layout.sizeThatFits(proposal:subviews:cache:)reports the size of the composite layout view.Layout.placeSubviews(in:proposal:subviews:cache:)assigns positions to the container's subviews.
You can define a basic layout type with only these two methods:
struct BasicVStack: Layout {
func sizeThatFits(
proposal: ProposedViewSize,
subviews: Subviews,
cache: inout ()
) -> CGSize {
// Calculate and return the size of the layout container.
}
func placeSubviews(
in bounds: CGRect,
proposal: ProposedViewSize,
subviews: Subviews,
cache: inout ()
) {
// Tell each subview where to appear.
}
}Use your layout the same way you use a built-in layout
container, by providing a ContentBuilder with the list of subviews
to arrange:
BasicVStack {
Text("A Subview")
Text("Another Subview")
}Support additional behaviors
You can optionally implement other protocol methods and properties to provide more layout container features:
- Define explicit horizontal and vertical layout guides for the container by
implementing
explicitAlignment(of:in:proposal:subviews:cache:)for each dimension. - Establish the preferred spacing around the container by implementing
spacing(subviews:cache:). - Indicate the axis of orientation for a container that has characteristics
of a stack by implementing the
layoutProperties-5rb5bstatic property. - Create and manage a cache to store computed values across different
layout protocol calls by implementing
makeCache(subviews:).
The protocol provides default implementations for these symbols if you don't implement them. See each method or property for details.
Add input parameters
You can define parameters as inputs to the layout, like you might
for a View:
struct BasicVStack: Layout {
var alignment: HorizontalAlignment
// ...
}Set the parameters at the point where you instantiate the layout:
BasicVStack(alignment: .leading) {
// ...
}If the layout provides default values for its parameters, you can omit the parameters at the call site, but you might need to keep the parentheses after the name of the layout, depending on how you specify the defaults. For example, suppose you set a default alignment for the basic stack in the parameter declaration:
struct BasicVStack: Layout {
var alignment: HorizontalAlignment = .center
// ...
}To instantiate this layout using the default center alignment, you don't have to specify the alignment value, but you do need to add empty parentheses:
BasicVStack() {
// ...
}The Swift compiler requires the parentheses in this case because of how the
layout protocol implements this call site syntax. Specifically, the layout's
callAsFunction(_:) method looks for an initializer with exactly zero
input arguments when you omit the parentheses from the call site.
You can enable the simpler call site for a layout that doesn't have an
implicit initializer of this type by explicitly defining one:
init() {
self.alignment = .center
}For information about Swift initializers, see Initialization in The Swift Programming Language.
Interact with subviews through their proxies
To perform layout, you need information about all of its subviews, which
are the views that your container arranges. While your layout can't
interact directly with its subviews, it can access a set of subview proxies
through the Subviews collection that each protocol method receives as
an input parameter. That type is an alias for the LayoutSubviews
collection type, which in turn contains LayoutSubview instances
that are the subview proxies.
You can get information about each subview from its proxy, like its
dimensions and spacing preferences. This enables
you to measure subviews before you commit to placing them. You also
assign a position to each subview by calling its proxy's
LayoutSubview.place(at:anchor:proposal:) method.
Call the method on each subview from within your implementation of the
layout's placeSubviews(in:proposal:subviews:cache:) method.
Access layout values
Views have layout values that you set with view modifiers.
Layout containers can choose to condition their behavior accordingly.
For example, a built-in HStack allocates space to its subviews based
in part on the priorities that you set with the View.layoutPriority(_:)
view modifier. Your layout container accesses this value for a subview by
reading the proxy's LayoutSubview.priority property.
You can also create custom layout values by creating a layout key.
Set a value on a view with the View.layoutValue(key:value:) view
modifier. Read the corresponding value from the subview's proxy using the
key as an index on the subview. For more information about creating,
setting, and accessing custom layout values, see LayoutValueKey.
From Apple’s SwiftUI documentation. Code samples there are Swift.
Used by
See also
More in Layout.
- AlignmentAn alignment in both axes.
- ContainerBackgroundPlacementThe placement of a container background.
- ContainerValuesReadableKeys of SwiftUI ContainerValues JavaScript can read.
- ContainerValuesWritableKeys of SwiftUI ContainerValues JavaScript can write.
- ControlSizeThe size classes, like regular or small, that you can apply to controls within a view.
- DocumentLaunchGeometryProxyA proxy for access to the frame of the scene and its title view.
- DynamicTypeSizeA Dynamic Type size, which specifies how large scalable content should be.
- EdgeAn enumeration to indicate one edge of a rectangle.
- EdgeInsetsThe inset distances for the sides of a rectangle.
- EdgeInsetsChainEdgeInsets with chained calls: SwiftUI.EdgeInsets.inset(...).
- EdgeSetAn efficient set of edges.
- GeometryProxyA proxy for access to the size and coordinate space (for anchor resolution) of the container view.