<!--
{
  "documentType" : "article",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/providing-data-to-the-view-hierarchy-with-custom-traits",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Providing data to the view hierarchy with custom traits"
}
-->

# Providing data to the view hierarchy with custom traits

Share data that needs to flow hierarchically across multiple levels of your view hierarchy.

## Discussion

A custom trait is a type that conforms to [`UITraitDefinition`](/documentation/UIKit/UITraitDefinition-3572h). Use a custom trait to pass application data, such as a color theme that a person selects in your app, through the objects in your view hierarchy that adopt [`UITraitEnvironment`](/documentation/UIKit/UITraitEnvironment). Represent data with a custom trait when you want to:

- Propagate data to many children, such as contained view controllers or subviews.
- Pass data to distant components; for example, from a [`UIWindowScene`](/documentation/UIKit/UIWindowScene) subclass to a view inside a stack of view controllers.
- Provide context about the environment, such as information about a containing view controller from the current view controller, without a dependency on the containing view controller.

Avoid using custom traits for data that you can pass directly between view controllers and views.

### Create, set, and access a custom trait

To create a custom trait, define a type that conforms to [`UITraitDefinition`](/documentation/UIKit/UITraitDefinition-3572h):

```swift
struct ContainedInSettingsTrait: UITraitDefinition {
    static let defaultValue = false
}
```

[`defaultValue`](/documentation/UIKit/UITraitDefinition-64c15/defaultValue) is the only required static property. The system infers the type for your custom trait from the type of the value you set for `defaultValue`. After you define your custom trait, set its value using your trait as the key in the `traitOverrides` property of an object in your view hierarchy:

```swift
self.traitOverrides[ContainedInSettingsTrait.self] = true
```

Then, the system propagates the trait and value to that object’s descendants in the view hierarchy. For example, if the object is a view controller, the system propagates the view controller’s trait collection with the override to the view controller’s view and subviews, and to any child view controllers.

Access the value of your trait using your trait as the key in a trait collection:

```swift
let value = traitCollection[ContainedInSettingsTrait.self]
```

### Simplify custom trait access with extensions

Add convenience properties to [`UITraitCollection`](/documentation/UIKit/UITraitCollection) and [`UIMutableTraits`](/documentation/UIKit/UIMutableTraits-8l00o) to make your custom trait easier to access. First, extend [`UITraitCollection`](/documentation/UIKit/UITraitCollection) with a property to get the value of your custom trait from a trait collection:

```swift
extension UITraitCollection {
    var isContainedInSettings: Bool { self[ContainedInSettingsTrait.self] }
}
```

Next, extend [`UIMutableTraits`](/documentation/UIKit/UIMutableTraits-8l00o) to get and set the value of your custom trait:

```swift
extension UIMutableTraits {
    var isContainedInSettings: Bool {
        get { self[ContainedInSettingsTrait.self] }
        set { self[ContainedInSettingsTrait.self] = newValue }
    }
}
```

Then, use standard property syntax to access and update your custom trait:

```swift
let traitCollection = UITraitCollection { mutableTraits in
    mutableTraits.isContainedInSettings = true
}

let value = traitCollection.isContainedInSettings
```

### Enhance custom trait interactions

Set optional properties of [`UITraitDefinition`](/documentation/UIKit/UITraitDefinition-3572h) to give your trait additional system capabilities and improve debugging:

- [`affectsColorAppearance`](/documentation/UIKit/UITraitDefinition-3572h/affectsColorAppearance): Set this to <doc://com.apple.documentation/documentation/Swift/true> when you use your custom trait to implement custom dynamic colors.
- [`name`](/documentation/UIKit/UITraitDefinition-3572h/name): Set this to a string value to identify your custom trait in the debugger.
- [`identifier`](/documentation/UIKit/UITraitDefinition-3572h/identifier): Set this to a string value to uniquely identify your custom trait, which makes it eligible for additional features such as encoding. Use reverse DNS format to make your identifier globally unique in your app.

The following example demonstrates setting these optional properties:

```swift
enum MyAppTheme: Int {
    case standard, pastel, bold, monochrome
}

struct MyAppThemeTrait: UITraitDefinition {
    static let defaultValue = MyAppTheme.standard
    static let affectsColorAppearance = true
    static let name = "Theme"
    static let identifier = "com.myapp.theme"
}
```

---

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)