Class

UIColor

An object that stores color data and sometimes opacity (alpha value).

Overview

Color objects can be created in a variety of ways:

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. Listing 1 sets the background and tint color of a view.

Listing 1

Using a UIColor object to set the color of a view controller’s view

self.backgroundView.backgroundColor = UIColor.gray()
self.backgroundView.tintColor = UIColor.blue()

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

Listing 2

Using a UIColor object to perform custom drawing

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 Setting the Graphics Context’s Drawing Color for the complete list of functions.

Color and Color Spaces

A UIColor object is typically represented internally as a Core Graphics color (CGColorRef) in a Core Graphics color space (CGColorSpaceRef). There are methods and properties that return the underlying color data. See Retrieving 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.

On versions of iOS before iOS 10, and for apps linked on a version of iOS prior to iOS 10, colors are created and returned in 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. Color component values within these color spaces are represented by values between 0.0 and 1.0. When a color is created, the input parameters are clamped to fit within this color space.

If your app was linked on or after iOS 10 and when running on iOS 10 or later, colors are created in extended color spaces:

  • kCGColorSpaceExtendedGray

  • kCGColorSpaceExtendedSRGB

When working in an extended color space, color values are not clamped to fit inside the color gamut, meaning that component values may be less than 0.0 or greater than 1.0. When displayed on an sRGB display, such colors are outside the gamut and will not be rendered accurately. However, extended color spaces are useful working color spaces when you want a pixel format and representation that other color spaces can be easily converted into. For example, a color in the display P3 color space that is not within the sRGB color gamut can still be converted to an extended sRGB format. Some of its values will be outside of the 0.0 to 1.0 range. However, when displayed on a device with a P3 display gamut, it would still be rendered correctly.

To summarize, when you need to worry about color spaces, use these extended color spaces as working color spaces. 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 doing so 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 also be safe to use from multiple threads.

Topics

Creating System Colors

darkTextColor

Returns the system color used for displaying text on a light background.

lightTextColor

Returns the system color used for displaying text on a dark background.

groupTableViewBackgroundColor

Returns the system color used for the background of a grouped table.

scrollViewTexturedBackgroundColor

Returns the system pattern color used to render the area behind scrollable content.

Deprecated
underPageBackgroundColor

Returns the system pattern color used to render the background of a page.

Deprecated
viewFlipsideBackgroundColor

Returns the system color used for the back side of a view while it is being flipped.

Deprecated

Creating a Color Object with a Predefined Color

blackColor

A color object in the sRGB color space whose grayscale value is 0.0 and whose alpha value is 1.0.

blueColor

A color object whose RGB values are 0.0, 0.0, and 1.0 and whose alpha value is 1.0.

brownColor

A color object whose RGB values are 0.6, 0.4, and 0.2 and whose alpha value is 1.0.

clearColor

A color object whose grayscale and alpha values are both 0.0.

cyanColor

A color object whose RGB values are 0.0, 1.0, and 1.0 and whose alpha value is 1.0.

darkGrayColor

A color object whose grayscale value is 1/3 and whose alpha value is 1.0.

grayColor

A color object whose grayscale value is 0.5 and whose alpha value is 1.0.

greenColor

A color object whose RGB values are 0.0, 1.0, and 0.0 and whose alpha value is 1.0.

lightGrayColor

A color object whose grayscale value is 2/3 and whose alpha value is 1.0.

magentaColor

A color object whose RGB values are 1.0, 0.0, and 1.0 and whose alpha value is 1.0.

orangeColor

A color object whose RGB values are 1.0, 0.5, and 0.0 and whose alpha value is 1.0.

purpleColor

A color object whose RGB values are 0.5, 0.0, and 0.5 and whose alpha value is 1.0.

redColor

A color object whose RGB values are 1.0, 0.0, and 0.0 and whose alpha value is 1.0.

whiteColor

A color object whose grayscale value is 1.0 and whose alpha value is 1.0.

yellowColor

A color object whose RGB values are 1.0, 1.0, and 0.0 and whose alpha value is 1.0.

Creating a Custom UIColor Object in a Specific Color Space

colorWithWhite:alpha:

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

colorWithHue:saturation:brightness:alpha:

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

colorWithRed:green:blue:alpha:

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

colorWithDisplayP3Red:green:blue:alpha:

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

initWithWhite:alpha:

Initializes and returns a color object using the specified opacity and grayscale values.

initWithHue:saturation:brightness:alpha:

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

initWithRed:green:blue:alpha:

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

initWithDisplayP3Red:green:blue:alpha:

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

colorNamed:

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

colorNamed:inBundle:compatibleWithTraitCollection:

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

Creating a UIColor Object from another Representation of Color

colorWithCIColor:

Creates a color object that encapsulates a Core Image color.

initWithCIColor:

Initializes and returns a color object that encapsulates a Core Image color.

colorWithCGColor:

Creates and returns a color object using the specified Quartz color reference.

initWithCGColor:

Initializes and returns a color object using the specified Quartz color reference.

colorWithAlphaComponent:

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

Creating a UIColor Object that Draws Using a Pattern

colorWithPatternImage:

Creates and returns a color object using the specified image.

initWithPatternImage:

Initializes and returns a color object using the specified Quartz color reference.

Setting the Graphics Context’s Drawing Color

set

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

setFill

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

setStroke

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

Retrieving Color Information

CGColor

The Quartz color reference that corresponds to the receiver’s color.

CGColor

The Quartz color reference that corresponds to the receiver’s color.

CIColor

The Core Image color associated with the receiver.

getHue:saturation:brightness:alpha:

Returns the components that make up the color in the HSB color space.

getRed:green:blue:alpha:

Returns the components that make up the color in the RGB color space.

getWhite:alpha:

Returns the grayscale components of the color.

Relationships

Inherits From