Class

UITraitCollection

A trait collection describes the iOS interface environment for your app, including traits such as horizontal and vertical size class, display scale, and user interface idiom. To create an adaptive interface, write code to adjust your app’s layout according to changes in these traits.

Overview

The iOS trait environment is exposed though the traitCollection property of the UITraitEnvironment protocol. This protocol is adopted by the following classes: UIScreen, UIWindow, UIViewController, UIPresentationController, and UIView. You access specific trait values using the UITraitCollection horizontalSizeClass, verticalSizeClass, displayScale, and userInterfaceIdiom properties. The values that express idiom and size traits are defined in the UIUserInterfaceIdiom and UIUserInterfaceSizeClass enumerations; the value for the display scale trait is expressed as a floating point number.

To make your view controllers and views responsive to changes in the iOS interface environment, override the traitCollectionDidChange(_:) method from the trait environment protocol. To customize view controller animations in response to interface environment changes, override the willTransition(to:with:) method of the UIContentContainer protocol.

This figure shows the horizontal (width) and vertical (height) size classes your app can encounter when running on various devices fullscreen.

For information about size classes your app encounters in Slide Over and Split View on iPad, read Slide Over and Split View Quick Start in Adopting Multitasking Enhancements on iPad.

You can create standalone trait collections to assist in matching against specific environments. The UITraitCollection class includes four specialized constructors as well as a constructor that lets you combine an array of trait collections, init(traitsFrom:).

One important use of standalone trait collections is to enable conditional use of images based on the current iOS interface environment. You can associate a trait collection with a UIImage instance by way of a UIImageAsset instance, as described in the overview section of UIImageAsset. For information on configuring asset catalogs graphically from within the Xcode IDE, see Asset Catalog Help.

You can employ a standalone trait collection to enable a two-column split view in landscape orientation on iPhone. See the setOverrideTraitCollection(_:forChildViewController:) method of the UIViewController class.

A standalone trait collection is also useful in customizing view appearance, by way of the appearance(for:) protocol method, as described in UIAppearance.

For the WWDC 2014 presentation on creating adaptive interfaces in iOS, see Building Adaptive Apps with UIKit.

3D Touch and Trait Collections

Starting in iOS 9, you can use this class to check whether the device on which your app is running supports 3D Touch. Read the value of the forceTouchCapability property on the trait collection for any object in your app with a trait environment. For information about trait environments, see UITraitEnvironment. For the possible values of the force touch capability property, see the UIForceTouchCapability enumeration.

Because a user can turn off 3D Touch in Settings, check the value of the forceTouchCapability property in your implementation of the traitCollectionDidChange(_:) method, and adjust your code paths according to the property’s value.

Symbols

Creating a Trait Collection

init(traitsFrom: [UITraitCollection])

Returns a new trait collection consisting of traits merged from a specified array of trait collections.

init(displayScale: CGFloat)

Returns a new trait collection containing only a specified display scale.

init(userInterfaceIdiom: UIUserInterfaceIdiom)

Returns a new trait collection containing only a specified interface idiom.

init(horizontalSizeClass: UIUserInterfaceSizeClass)

Returns a new trait collection containing only a specified horizontal size class.

init(verticalSizeClass: UIUserInterfaceSizeClass)

Returns a new trait collection containing only a specified vertical size class.

init(forceTouchCapability: UIForceTouchCapability)

Creates a trait collection containing only a specified force touch capability trait.

Retrieving Trait Information

var displayScale: CGFloat

The display scale of the trait collection.

var horizontalSizeClass: UIUserInterfaceSizeClass

The horizontal size class of the trait collection.

var userInterfaceIdiom: UIUserInterfaceIdiom

The user interface idiom of the trait collection.

var verticalSizeClass: UIUserInterfaceSizeClass

The vertical size class of the trait collection.

var forceTouchCapability: UIForceTouchCapability

The force touch capability value of the trait collection.

Comparing Trait Collections

func containsTraits(in: UITraitCollection?)

Returns a Boolean value that indicates whether a trait collection contains all of another trait collection’s values.

Constants

UIForceTouchCapability

Keys that indicate the availability of 3D Touch on a device. Only certain devices support 3D Touch. On those that do, the user can disable 3D Touch in the Accessibility area in Settings.

Relationships

Inherits From