iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIColor Class Reference

Options
Deployment Target:

On This Page
Language:

UIColor

A UIColor object represents color and sometimes opacity (alpha value). You can use UIColor objects to store color data, and during drawing you can use them to set the current fill and stroke colors.

Many methods in UIKit require you to specify color data using a UIColor object, and for general color needs it should be your main way of specifying colors. The color spaces used by this object are optimized for use on iOS-based devices and are therefore appropriate for most drawing needs. If you prefer to use Core Graphics colors and color spaces instead, however, you may do so.

Color objects are immutable and so it is safe to use them from multiple threads in your app.

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

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

    Declaration

    Objective-C

    + (UIColor * _Nonnull)colorWithWhite:(CGFloat)white alpha:(CGFloat)alpha

    Parameters

    white

    The grayscale value of the color object, specified as a value from 0.0 to 1.0.

    alpha

    The opacity value of the color object, specified as a value from 0.0 to 1.0.

    Return Value

    The color object. The color information represented by this object is in the device gray colorspace.

    Discussion

    Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    + (UIColor * _Nonnull)colorWithHue:(CGFloat)hue saturation:(CGFloat)saturation brightness:(CGFloat)brightness alpha:(CGFloat)alpha

    Parameters

    hue

    The hue component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

    saturation

    The saturation component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

    brightness

    The brightness (or value) component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

    alpha

    The opacity value of the color object, specified as a value from 0.0 to 1.0.

    Return Value

    The color object. The color information represented by this object is in the device RGB colorspace.

    Discussion

    Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    + (UIColor * _Nonnull)colorWithRed:(CGFloat)red green:(CGFloat)green blue:(CGFloat)blue alpha:(CGFloat)alpha

    Parameters

    red

    The red component of the color object, specified as a value from 0.0 to 1.0.

    green

    The green component of the color object, specified as a value from 0.0 to 1.0.

    blue

    The blue component of the color object, specified as a value from 0.0 to 1.0.

    alpha

    The opacity value of the color object, specified as a value from 0.0 to 1.0.

    Return Value

    The color object. The color information represented by this object is in the device RGB colorspace.

    Discussion

    Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    + (UIColor * _Nonnull)colorWithCGColor:(CGColorRef _Nonnull)cgColor

    Parameters

    cgColor

    A reference to a Quartz color.

    Return Value

    The color object. The color information represented by this object is in the native colorspace of the specified Quartz color.

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a color object using the specified image.

    Declaration

    Objective-C

    + (UIColor * _Nonnull)colorWithPatternImage:(UIImage * _Nonnull)image

    Parameters

    image

    The image to use when creating the pattern color.

    Return Value

    The pattern color.

    Discussion

    You can use pattern colors to set the fill or stroke color just as you would a solid color. During drawing, the image in the pattern color is tiled as necessary to cover the given area.

    By default, the phase of the returned color is 0, which causes the top-left corner of the image to be aligned with the drawing origin. To change the phase, make the color the current color and then use the CGContextSetPatternPhase function to change the phase.

    Availability

    Available in iOS 2.0 and later.

  • Converts a Core Image color object to its UIColor equivalent

    Declaration

    Objective-C

    + (UIColor * _Nonnull)colorWithCIColor:(CIColor * _Nonnull)ciColor

    Parameters

    ciColor

    The Core Image color to convert.

    Return Value

    The UIColor object corresponding to the specified Core Image color.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func colorWithAlphaComponent(_ alpha: CGFloat) -> UIColor

    Objective-C

    - (UIColor * _Nonnull)colorWithAlphaComponent:(CGFloat)alpha

    Parameters

    alpha

    The opacity value of the new UIColor object.

    Return Value

    The new UIColor object.

    Discussion

    A subclass with explicit opacity components should override this method to return a color with the specified alpha.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(white white: CGFloat, alpha alpha: CGFloat)

    Objective-C

    - (UIColor * _Nonnull)initWithWhite:(CGFloat)white alpha:(CGFloat)alpha

    Parameters

    white

    The grayscale value of the color object, specified as a value from 0.0 to 1.0.

    alpha

    The opacity value of the color object, specified as a value from 0.0 to 1.0.

    Return Value

    An initialized color object. The color information represented by this object is in the device gray colorspace.

    Discussion

    Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

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

    Objective-C

    - (UIColor * _Nonnull)initWithHue:(CGFloat)hue saturation:(CGFloat)saturation brightness:(CGFloat)brightness alpha:(CGFloat)alpha

    Parameters

    hue

    The hue component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

    saturation

    The saturation component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

    brightness

    The brightness (or value) component of the color object in the HSB color space, specified as a value from 0.0 to 1.0.

    alpha

    The opacity value of the color object, specified as a value from 0.0 to 1.0.

    Return Value

    An initialized color object. The color information represented by this object is in the device RGB colorspace.

    Discussion

    Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

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

    Objective-C

    - (UIColor * _Nonnull)initWithRed:(CGFloat)red green:(CGFloat)green blue:(CGFloat)blue alpha:(CGFloat)alpha

    Parameters

    red

    The red component of the color object, specified as a value from 0.0 to 1.0.

    green

    The green component of the color object, specified as a value from 0.0 to 1.0.

    blue

    The blue component of the color object, specified as a value from 0.0 to 1.0.

    alpha

    The opacity value of the color object, specified as a value from 0.0 to 1.0.

    Return Value

    An initialized color object. The color information represented by this object is in the device RGB colorspace.

    Discussion

    Values below 0.0 are interpreted as 0.0, and values above 1.0 are interpreted as 1.0.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(CGColor cgColor: CGColor)

    Objective-C

    - (UIColor * _Nonnull)initWithCGColor:(CGColorRef _Nonnull)cgColor

    Parameters

    cgColor

    A reference to a Quartz color.

    Return Value

    An initialized color object. The color information represented by this object is in the native colorspace of the specified Quartz color.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    init(patternImage image: UIImage)

    Objective-C

    - (UIColor * _Nonnull)initWithPatternImage:(UIImage * _Nonnull)image

    Parameters

    image

    The image to use when creating the pattern color.

    Return Value

    The pattern color.

    Discussion

    You can use pattern colors to set the fill or stroke color just as you would a solid color. During drawing, the image in the pattern color is tiled as necessary to cover the given area.

    By default, the phase of the returned color is 0, which causes the top-left corner of the image to be aligned with the drawing origin. To change the phase, make the color the current color and then use the CGContextSetPatternPhase function to change the phase.

    Availability

    Available in iOS 2.0 and later.

  • Initializes and returns a color object using the specified Core Image color.

    Declaration

    Swift

    init(CIColor ciColor: CIColor)

    Objective-C

    - (UIColor * _Nonnull)initWithCIColor:(CIColor * _Nonnull)ciColor

    Parameters

    ciColor

    The Core Image color to convert.

    Return Value

    An initialized color object.

    Availability

    Available in iOS 5.0 and later.

  • Returns a color object whose grayscale value is 0.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func blackColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)blackColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose grayscale value is 1/3 and whose alpha value is 1.0.

    Declaration

    Swift

    class func darkGrayColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)darkGrayColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose grayscale value is 2/3 and whose alpha value is 1.0.

    Declaration

    Swift

    class func lightGrayColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)lightGrayColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose grayscale value is 1.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func whiteColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)whiteColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose grayscale value is 0.5 and whose alpha value is 1.0.

    Declaration

    Swift

    class func grayColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)grayColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 1.0, 0.0, and 0.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func redColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)redColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 0.0, 1.0, and 0.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func greenColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)greenColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 0.0, 0.0, and 1.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func blueColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)blueColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 0.0, 1.0, and 1.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func cyanColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)cyanColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 1.0, 1.0, and 0.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func yellowColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)yellowColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 1.0, 0.0, and 1.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func magentaColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)magentaColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 1.0, 0.5, and 0.0 and whose alpha value is 1.0.

    Declaration

    Swift

    class func orangeColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)orangeColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose RGB values are 0.5, 0.0, and 0.5 and whose alpha value is 1.0.

    Declaration

    Swift

    class func purpleColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)purpleColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func brownColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)brownColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

  • Returns a color object whose grayscale and alpha values are both 0.0.

    Declaration

    Swift

    class func clearColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)clearColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func lightTextColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)lightTextColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func darkTextColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)darkTextColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func groupTableViewBackgroundColor() -> UIColor

    Objective-C

    + (UIColor * _Nonnull)groupTableViewBackgroundColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    + (UIColor * _Nonnull)viewFlipsideBackgroundColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 7.0.

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

    Declaration

    Objective-C

    + (UIColor * _Nonnull)scrollViewTexturedBackgroundColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 3.2 and later.

    Deprecated in iOS 7.0.

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

    Declaration

    Objective-C

    + (UIColor * _Nonnull)underPageBackgroundColor

    Return Value

    The UIColor object.

    Availability

    Available in iOS 5.0 and later.

    Deprecated in iOS 7.0.

  • The Quartz color reference that corresponds to the receiver’s color. (read-only)

    Declaration

    Swift

    var CGColor: CGColor { get }

    Objective-C

    @property(nonatomic, readonly) CGColorRef _Nonnull CGColor

    Availability

    Available in iOS 2.0 and later.

  • The Core Image color associated with the receiver. (read-only)

    Declaration

    Swift

    var CIColor: CIColor { get }

    Objective-C

    @property(nonatomic, readonly) CIColor * _Nonnull CIColor

    Discussion

    This property throws an exception if the color object was not initialized with a Core Image color.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func getHue(_ hue: UnsafeMutablePointer<CGFloat>, saturation saturation: UnsafeMutablePointer<CGFloat>, brightness brightness: UnsafeMutablePointer<CGFloat>, alpha alpha: UnsafeMutablePointer<CGFloat>) -> Bool

    Objective-C

    - (BOOL)getHue:(CGFloat * _Nullable)hue saturation:(CGFloat * _Nullable)saturation brightness:(CGFloat * _Nullable)brightness alpha:(CGFloat * _Nullable)alpha

    Parameters

    hue

    On return, the hue component of the color object, specified as a value between 0.0 and 1.0.

    saturation

    On return, the saturation component of the color object, specified as a value between 0.0 and 1.0.

    brightness

    On return, the brightness component of the color object, specified as a value between 0.0 and 1.0.

    alpha

    On return, the opacity component of the color object, specified as a value between 0.0 and 1.0.

    Return Value

    YEStrue if the color could be converted, NOfalse otherwise.

    Discussion

    If the color is in a compatible color space, the color is converted into the HSB color space and its components are returned to your application. If the color is not in a compatible color space, the parameters are unchanged.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func getRed(_ red: UnsafeMutablePointer<CGFloat>, green green: UnsafeMutablePointer<CGFloat>, blue blue: UnsafeMutablePointer<CGFloat>, alpha alpha: UnsafeMutablePointer<CGFloat>) -> Bool

    Objective-C

    - (BOOL)getRed:(CGFloat * _Nullable)red green:(CGFloat * _Nullable)green blue:(CGFloat * _Nullable)blue alpha:(CGFloat * _Nullable)alpha

    Parameters

    red

    On return, the red component of the color object, specified as a value between 0.0 and 1.0.

    green

    On return, the green component of the color object, specified as a value between 0.0 and 1.0.

    blue

    On return, the blue component of the color object, specified as a value between 0.0 and 1.0.

    alpha

    On return, the opacity component of the color object, specified as a value between 0.0 and 1.0.

    Return Value

    YEStrue if the color could be converted, NOfalse otherwise.

    Discussion

    If the color is in a compatible color space, the color is converted into RGB format and its components are returned to your application. If the color is not in a compatible color space, the parameters are unchanged.

    Availability

    Available in iOS 5.0 and later.

  • Returns the grayscale components of the color.

    Declaration

    Swift

    func getWhite(_ white: UnsafeMutablePointer<CGFloat>, alpha alpha: UnsafeMutablePointer<CGFloat>) -> Bool

    Objective-C

    - (BOOL)getWhite:(CGFloat * _Nullable)white alpha:(CGFloat * _Nullable)alpha

    Parameters

    white

    On return, the grayscale component of the color object, specified as a value between 0.0 and 1.0.

    alpha

    On return, the opacity component of the color object, specified as a value between 0.0 and 1.0.

    Return Value

    YEStrue if the color could be converted, NOfalse otherwise.

    Discussion

    If the color is in a compatible color space, the color is converted into grayscale format and returned to your application. If the color is not in a compatible color space, the parameters are unchanged.

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    func set()

    Objective-C

    - (void)set

    Discussion

    If you subclass UIColor, you must implement this method in your subclass. Your custom implementation should modify both the stroke and fill color in the current graphics context by setting them both to the color represented by the receiver.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func setFill()

    Objective-C

    - (void)setFill

    Discussion

    If you subclass UIColor, you must implement this method in your subclass. Your custom implementation should modify the fill color in the current graphics context by setting it to the color represented by the receiver.

    Availability

    Available in iOS 2.0 and later.

    See Also

    – set

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

    Declaration

    Swift

    func setStroke()

    Objective-C

    - (void)setStroke

    Discussion

    If you subclass UIColor, you must implement this method in your subclass. Your custom implementation should modify the stroke color in the current graphics context by setting it to the color represented by the receiver.

    Availability

    Available in iOS 2.0 and later.

    See Also

    – set