<!--
{
  "availability" : [
    "iOS: 16.0.0 -",
    "iPadOS: 16.0.0 -",
    "macCatalyst: 16.0.0 -",
    "macOS: 13.0.0 -",
    "tvOS: 16.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 9.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "SwiftUI",
  "identifier" : "/documentation/SwiftUI/LayoutValueKey",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "SwiftUI"
    ],
    "preciseIdentifier" : "s:7SwiftUI14LayoutValueKeyP"
  },
  "title" : "LayoutValueKey"
}
-->

# LayoutValueKey

A key for accessing a layout value of a layout container’s subviews.

```
protocol LayoutValueKey
```

## Overview

If you create a custom layout by defining a type that conforms to the
[`Layout`](/documentation/SwiftUI/Layout) protocol, you can also create custom layout values
that you set on individual views, and that your container view can access
to guide its layout behavior. Your custom values resemble
the built-in layout values that you set with view modifiers
like [`layoutPriority(_:)`](/documentation/SwiftUI/View/layoutPriority(_:)) and [`zIndex(_:)`](/documentation/SwiftUI/View/zIndex(_:)), but have a
purpose that you define.

To create a custom layout value, define a type that conforms to the
`LayoutValueKey` protocol and implement the one required property that
returns the default value of the property. For example, you can create
a property that defines an amount of flexibility for a view, defined as
an optional floating point number with a default value of `nil`:

```
private struct Flexibility: LayoutValueKey {
    static let defaultValue: CGFloat? = nil
}
```

The Swift compiler infers this particular key’s associated type as an
optional <doc://com.apple.documentation/documentation/CoreFoundation/CGFloat-swift.struct>
from this definition.

### Set a value on a view

Set the value on a view by adding the [`layoutValue(key:value:)`](/documentation/SwiftUI/View/layoutValue(key:value:))
view modifier to the view. To make your custom value easier to work
with, you can do this in a convenience modifier in an extension of the
[`View`](/documentation/SwiftUI/View) protocol:

```
extension View {
    func layoutFlexibility(_ value: CGFloat?) -> some View {
        layoutValue(key: Flexibility.self, value: value)
    }
}
```

Use your modifier to set the value on any views that need a nondefault
value:

```
BasicVStack {
    Text("One View")
    Text("Another View")
        .layoutFlexibility(3)
}
```

Any view that you don’t explicitly set a value for uses the default
value, as with the first [`Text`](/documentation/SwiftUI/Text) view, above.

### Retrieve a value during layout

Access a custom layout value using the key as an index
on subview’s proxy (an instance of [`LayoutSubview`](/documentation/SwiftUI/LayoutSubview))
and use the value to make decisions about sizing, placement, or other
layout operations. For example, you might read the flexibility value
in your layout view’s [`sizeThatFits(_:)`](/documentation/SwiftUI/LayoutSubview/sizeThatFits(_:)) method, and
adjust your size calculations accordingly:

```
extension BasicVStack {
    func sizeThatFits(
        proposal: ProposedViewSize,
        subviews: Subviews,
        cache: inout Void
    ) -> CGSize {

        // Map the flexibility property of each subview into an array.
        let flexibilities = subviews.map { subview in
            subview[Flexibility.self]
        }

        // Calculate and return the size of the layout container.
        // ...
    }
}
```

## Topics

### Providing a default value

[`defaultValue`](/documentation/SwiftUI/LayoutValueKey/defaultValue)

The default value of the key.

[`Value`](/documentation/SwiftUI/LayoutValueKey/Value)

The type of the key’s value.


---

Copyright &copy; 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)