Class

UITraitCollection

The iOS interface environment for your app, defined by traits such as horizontal and vertical size class, display scale, and user interface idiom.

Declaration

@interface UITraitCollection : NSObject

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. To create an adaptive interface, write code to adjust your app’s layout according to changes in these traits. 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 willTransitionToTraitCollection:withTransitionCoordinator: method of the UIContentContainer protocol.

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

Figure 1

Size classes

Examples of size classes on iOS devices. The top figures show the size classes for a 10.5 inch iPad as horizontally and vertically regular. For an iPhone X, the vertical size class in a portrait orientation is regular, but all of the other size classes are compact.

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, traitCollectionWithTraitsFromCollections:.

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 appearanceForTraitCollection: protocol method, as described in UIAppearance.

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.

Topics

Creating a Trait Collection

- init

Returns a new trait collection whose traits are set to their default (unspecified) values.

+ traitCollectionWithTraitsFromCollections:

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

+ traitCollectionWithUserInterfaceIdiom:

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

+ traitCollectionWithHorizontalSizeClass:

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

+ traitCollectionWithVerticalSizeClass:

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

+ traitCollectionWithUserInterfaceStyle:

Returns a new trait collection containing only the specified user interface style trait.

+ traitCollectionWithAccessibilityContrast:

Returns a new trait collection containing only the specified accessibility contrast trait.

+ traitCollectionWithUserInterfaceLevel:

Returns a new trait collection containing only the specified user interface level trait.

+ traitCollectionWithLegibilityWeight:

Returns a new trait collection containing only the specified legibility weight trait.

+ traitCollectionWithForceTouchCapability:

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

+ traitCollectionWithDisplayScale:

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

+ traitCollectionWithDisplayGamut:

Returns a new trait collection containing only the specified display gamut trait.

+ traitCollectionWithLayoutDirection:

Returns a new trait collection containing only the specified layout direction trait.

+ traitCollectionWithPreferredContentSizeCategory:

Returns a new trait collection containing only the specified content size category trait.

Getting the Current Traits

currentTraitCollection

The complete set of traits for the current environment.

Retrieving Size Class Traits

horizontalSizeClass

The horizontal size class of the trait collection.

verticalSizeClass

The vertical size class of the trait collection.

UIUserInterfaceSizeClass

Defines the size class of a view.

Retrieving Display-Related Traits

displayScale

The display scale of the trait collection.

displayGamut

The gamut of the current display.

UIDisplayGamut

Constants indicating the gamut of the current display.

Retrieving Interface-Related Traits

userInterfaceStyle

The style associated with the user interface.

UIUserInterfaceStyle

Constants indicating the interface style for the app.

userInterfaceIdiom

The user interface idiom of the trait collection.

UIUserInterfaceIdiom

The interface type for the device or an object that has a trait environment, such as a view and view controller.

userInterfaceLevel

The elevation level of the interface.

UIUserInterfaceLevel

Constants indicating the visual level for content in the window.

layoutDirection

The layout direction associated with the current environment.

UITraitEnvironmentLayoutDirection

Constants indicating the layout direction associated with the current environment.

accessibilityContrast

The accessibility contrast associated with the current environment.

UIAccessibilityContrast

Constants indicating the accessibility contrast setting.

legibilityWeight

The font weight to apply to text.

UILegibilityWeight

Constants indicating the weight to apply to text in your interface.

Retrieving the Force Touch Capability Traits

forceTouchCapability

The force touch capability value of the trait collection.

UIForceTouchCapability

Keys that indicate the availability of 3D Touch on a device.

Retrieving Content Size Category Information

preferredContentSizeCategory

The font sizing option preferred by the user.

UIContentSizeCategory

Constants indicating the preferred size of your content.

UIContentSizeCategoryCompareToCategory

Compares two content size category values to determine whether they are equal or whether one is larger than the other.

UIContentSizeCategoryIsAccessibilityCategory

Returns a Boolean value indicating whether the content size category belongs to the group of accessibility-related sizes.

Comparing Trait Collections

- containsTraitsInCollection:

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

- hasDifferentColorAppearanceComparedToTraitCollection:

Returns a Boolean value indicating whether changing between the specified and current trait collections would affect color values.

Getting an Image Configuration Object

imageConfiguration

An image configuration object compatible with this trait collection.

Performing Actions with the Current Traits

- performAsCurrentTraitCollection:

Executes custom code using the traits of the current trait collection.

Relationships

Inherits From

See Also

Adaptivity

Responding to Changing Display Modes on Apple TV

Change images and resources dynamically when the screen gamut on your device changes.

UITraitEnvironment

A set of methods that makes the iOS interface environment available to your app.

UIAdaptivePresentationControllerDelegate

A set of methods that, in conjunction with a presentation controller, determine how to respond to trait changes in your app.

UIContentContainer

A set of methods for adapting the contents of your view controllers to size and trait changes.