Class

UIColor

An object that stores color data and sometimes opacity.

Declaration

class UIColor : NSObject

Overview

Color objects can be created in a variety of ways:

  • UIKit provides standard system colors for matching the colors in your own UI objects to those provided by UIKit. You can reproduce these colors without needing to understand the underlying representation of color. See UI Element Colors.

  • UIKit provides definitions for standard colors such as red, orange, yellow, and so on. See Standard Colors.

  • You can create a custom color in a Core Graphics color space. See Creating a Color from Component Values.

  • You can create a color object from another object, such as another UIColor object, a Core Graphics representation of a color, or a Core Image color. See Creating a Color from Another Color Object.

  • You can create a color from a UIImage object and use it to paint a repeating pattern. See Creating a Pattern-Based Color.

The most common way to use a UIColor object is to provide it to some other object in UIKit. For example, the UIView class (and its descendants) include background and tint colors to affect how they are drawn onscreen. The following code example sets the background and tint color of a view.

backgroundView.backgroundColor = UIColor.systemGray
backgroundView.tintColor = UIColor.systemBlue

When performing custom drawing, a UIColor object provides methods that set the fill or stroke colors of the current graphics context. The following code example shows a simple example of custom drawing inside a view.

class CircleView: UIView {
    
    override func draw(_ rect: CGRect) {
        let ovalBounds = self.bounds.insetBy(dx: 10, dy: 10)
        let oval = UIBezierPath(ovalIn: ovalBounds)
        let brightRed = UIColor(displayP3Red: 1.0, green: 0.0, blue: 0.0, alpha: 1.0)
        brightRed.setFill()
        oval.fill()
    }
}

See Applying the Color to the Drawing Environment for the complete list of functions.

Understand Color Space Usage

A UIColor object typically stores its color value as a Core Graphics color (CGColor) in a Core Graphics color space (CGColorSpace). There are methods and properties that return the underlying color data, which are described in Getting the Color Information. When creating a custom color, the underlying color space and the range of values for each color component vary based on the iOS version.

For apps linked against the iOS 9 SDK and earlier, or running on iOS 9 and earlier, colors use one of two color spaces:

  • Device-Dependent Gray

  • Device-Dependent RGB

These device color spaces correspond closely to the display characteristics of the sRGB color space. Component values within these color spaces are in the range 0.0 to 1.0. When you create a color, the color object clamps values to ensure they fit within this range.

For apps linked against the iOS 10 SDK or later, and running on iOS 10 or later, colors use the following extended color spaces:

In the extended color spaces, UIColor does not clamp values to fit inside the color gamut, meaning that component values may be less than 0.0 or greater than 1.0. On an sRGB display, such colors are outside the gamut and will not be rendered accurately. However, the extended color spaces are useful when you want a pixel format and representation that other color spaces can be easily converted into. For example, you can still convert a color in the display P3 color space to an extended sRGB format, even if that color is not within the sRGB color gamut. When you convert such a color, some of its values will fall outside of the 0.0 to 1.0 range. However, the color still renders correctly on a device with a P3 display gamut.

When employing custom colors, use extended color spaces to store your color values. When you need to worry about representing that color as closely as possible in a specific color space, convert the color from the extended color space into the target color space.

Subclassing Notes

Most developers have no need to subclass UIColor. The only time it might be necessary is if you require support for additional color spaces or color models. If you do subclass, the properties and methods you add must be safe to use from multiple threads.

Topics

Getting Existing Colors

UI Element Colors

The standard color objects you can use for labels, text, backgrounds, links, and more.

Standard Colors

The standard color objects for specific shades, such as red, blue, green, black, white, and more.

Creating a Color from Component Values

init(white: CGFloat, alpha: CGFloat)

Creates a color object using the specified opacity and grayscale values.

init(hue: CGFloat, saturation: CGFloat, brightness: CGFloat, alpha: CGFloat)

Creates a color object using the specified opacity and HSB color space component values.

init(red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)

Creates a color object using the specified opacity and RGB component values.

init(displayP3Red: CGFloat, green: CGFloat, blue: CGFloat, alpha: CGFloat)

Creates a color object using the specified opacity and RGB component values in the Display P3 color space.

init?(named: String)

Creates a color object using the information stored in the named asset.

init?(named: String, in: Bundle?, compatibleWith: UITraitCollection?)

Creates a color object using the named asset that is compatible with the specified trait collection.

Creating a Color Dynamically

init(dynamicProvider: (UITraitCollection) -> UIColor)

Creates a color object that generates its color data dynamically using the specified block.

Creating a Color from Another Color Object

init(ciColor: CIColor)

Creates a color object that encapsulates a Core Image color.

init(cgColor: CGColor)

Creates a color object using the specified Quartz color reference.

func withAlphaComponent(CGFloat) -> UIColor

Creates a color object that has the same color space and component values as the receiver, but has the specified alpha component.

Creating a Pattern-Based Color

init(patternImage: UIImage)

Creates a color object using the specified image object.

Applying the Color to the Drawing Environment

func set()

Sets the color of subsequent stroke and fill operations to the color that the receiver represents.

func setFill()

Sets the color of subsequent fill operations to the color that the receiver represents.

func setStroke()

Sets the color of subsequent stroke operations to the color that the receiver represents.

Getting the Color Information

Resolving a Dynamically Generated Color

func resolvedColor(with: UITraitCollection) -> UIColor

Returns the version of the current color that takes the specified traits into account.