<!--
{
  "availability" : [
    "macOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "AppKit",
  "identifier" : "/documentation/AppKit/NSColor",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AppKit"
    ],
    "preciseIdentifier" : "c:objc(cs)NSColor"
  },
  "title" : "NSColor"
}
-->

# NSColor

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

```
class NSColor
```

## Overview

Many methods in AppKit require you to specify color data using an [`NSColor`](/documentation/AppKit/NSColor) object; when drawing you use them to set the current fill and stroke colors. Color objects are immutable and thread-safe. You can create color objects in many ways:

- Load colors from an asset catalog. Colors created from assets can adapt automatically to system appearance changes.
- Use the semantic colors for custom UI elements, so that they match the appearance of other AppKit views; see [UI element colors](/documentation/AppKit/ui-element-colors).
- Use the adaptable system colors, such as [`systemBlue`](/documentation/AppKit/NSColor/systemBlue), when you want a specific tint that looks correct in both light and dark environments.
- Create a color object from another object, such as a Core Graphics representation of a color, or a Core Image color.
- Create a color from an [`NSImage`](/documentation/AppKit/NSImage) object, and paint a repeating pattern instead of using a solid color.
- Create a color by applying a transform to another [`NSColor`](/documentation/AppKit/NSColor) object. For example, you might perform a blend operation between two colors, or you might create a color that represents the same color, but in a different color space.
- Create custom colors using raw component values, and a variety of color spaces, when you need to represent user-specified colors.

For user-specified colors, you can also display a color panel and let the user specify the color. For information about color panels, see [`NSColorPanel`](/documentation/AppKit/NSColorPanel).

### Color and color spaces

A color object is typically represented internally as a Core Graphics color (<doc://com.apple.documentation/documentation/CoreGraphics/CGColor>) in a Core Graphics color space (<doc://com.apple.documentation/documentation/CoreGraphics/CGColorSpace>). Colors can also be created in extended color spaces:

- [`extendedSRGB`](/documentation/AppKit/NSColorSpace/extendedSRGB)
- [`extendedGenericGamma22Gray`](/documentation/AppKit/NSColorSpace/extendedGenericGamma22Gray)

When you need to worry about color spaces, use 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.

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 won’t render accurately. However, extended color spaces are useful as 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 can convert to an extended sRGB format, even if it isn’t within the sRGB color gamut. While some of the converted color’s values are outside of the 0-1.0 range, the color renders correctly when viewed on a device with a P3 display gamut.

It is a programmer error to access color components of a color space that the `NSColor` object does not support. For example, you cannot access the [`redComponent`](/documentation/AppKit/NSColor/redComponent) property and [`getRed(_:green:blue:alpha:)`](/documentation/AppKit/NSColor/getRed(_:green:blue:alpha:)) method on a color that uses the CMYK color space. Further, the [`getComponents(_:)`](/documentation/AppKit/NSColor/getComponents(_:)) method and [`numberOfComponents`](/documentation/AppKit/NSColor/numberOfComponents) property work only in color spaces that have individual components. As such, they return the components of color objects as individual floating-point values regardless of whether they’re based on [`NSColorSpace`](/documentation/AppKit/NSColorSpace) objects or named color spaces. However, older component-fetching methods such as [`getRed(_:green:blue:alpha:)`](/documentation/AppKit/NSColor/getRed(_:green:blue:alpha:)) are effective only on color objects based on named color spaces.

If you have a color object in an unknown color space and you want to extract its components, convert the color object to a known color space and then use the component accessor methods of that color space.

For design guidance, see Human Interface Guidelines > [Color](https://developer.apple.com/design/human-interface-guidelines/color/).

## Topics

### Getting and creating colors

Get one of the AppKit-defined colors, load colors from asset catalogs, or create custom colors for your app.

[UI element colors](/documentation/AppKit/ui-element-colors)

Retrieve standard color objects for use with windows, controls, labels, text, selections and other content in your app.

[Standard colors](/documentation/AppKit/standard-colors)

Retrieve the standard color objects for common colors like red, blue, green, black, white, and more.

[Color creation](/documentation/AppKit/color-creation)

Load colors from asset catalogs, and create colors from raw component values, such as those used by grayscale, RGB, HSB, and CMYK colors.

### Applying specific appearances to colors

[`withSystemEffect(_:)`](/documentation/AppKit/NSColor/withSystemEffect(_:))

Returns a new color object that represents the current color modified to include the specified visual effect.

[`NSColor.SystemEffect`](/documentation/AppKit/NSColor/SystemEffect)

Constants for user interactions that change the appearance of a view or control.

### Transforming existing color objects

[`usingColorSpace(_:)`](/documentation/AppKit/NSColor/usingColorSpace(_:))

Creates a new color object representing the color of the current color object in the specified color space.

[`blended(withFraction:of:)`](/documentation/AppKit/NSColor/blended(withFraction:of:))

Creates a new color object whose component values are a weighted sum of the current color object and the specified color object’s.

[`withAlphaComponent(_:)`](/documentation/AppKit/NSColor/withAlphaComponent(_:))

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

[`highlight(withLevel:)`](/documentation/AppKit/NSColor/highlight(withLevel:))

Creates a new color object that represents a blend between the current color and the highlight color.

[`shadow(withLevel:)`](/documentation/AppKit/NSColor/shadow(withLevel:))

Creates a new color object that represents a blend between the current color and the shadow color.

### Copying and pasting color Information

[`init(from:)`](/documentation/AppKit/NSColor/init(from:))

Creates a color object from color data currently on the pasteboard.

[`write(to:)`](/documentation/AppKit/NSColor/write(to:))

Writes the color object’s data to the specified pasteboard.

### Retrieving component values from color objects

[`getCyan(_:magenta:yellow:black:alpha:)`](/documentation/AppKit/NSColor/getCyan(_:magenta:yellow:black:alpha:))

Returns the color object’s CMYK and opacity values.

[`getHue(_:saturation:brightness:alpha:)`](/documentation/AppKit/NSColor/getHue(_:saturation:brightness:alpha:))

Returns the color object’s HSB component and opacity values in the respective arguments.

[`getRed(_:green:blue:alpha:)`](/documentation/AppKit/NSColor/getRed(_:green:blue:alpha:))

Returns the color object’s RGB component and opacity values in the respective arguments.

[`getWhite(_:alpha:)`](/documentation/AppKit/NSColor/getWhite(_:alpha:))

Returns the grayscale and alpha values of the color.

[`numberOfComponents`](/documentation/AppKit/NSColor/numberOfComponents)

The number of components in the color.

[`getComponents(_:)`](/documentation/AppKit/NSColor/getComponents(_:))

Returns the components of the color as an array.

### Retrieving individual components

[`alphaComponent`](/documentation/AppKit/NSColor/alphaComponent)

The alpha (opacity) component value of the color.

[`whiteComponent`](/documentation/AppKit/NSColor/whiteComponent)

The white component value of the color.

[`redComponent`](/documentation/AppKit/NSColor/redComponent)

The red component value of the color.

[`greenComponent`](/documentation/AppKit/NSColor/greenComponent)

The green component value of the color.

[`blueComponent`](/documentation/AppKit/NSColor/blueComponent)

The blue component value of the color.

[`cyanComponent`](/documentation/AppKit/NSColor/cyanComponent)

The cyan component value of the color.

[`magentaComponent`](/documentation/AppKit/NSColor/magentaComponent)

The magenta component value of the color.

[`yellowComponent`](/documentation/AppKit/NSColor/yellowComponent)

The yellow component value of the color.

[`blackComponent`](/documentation/AppKit/NSColor/blackComponent)

The black component value of the color.

[`hueComponent`](/documentation/AppKit/NSColor/hueComponent)

The hue component value of the color.

[`saturationComponent`](/documentation/AppKit/NSColor/saturationComponent)

The saturation component value of the color.

[`brightnessComponent`](/documentation/AppKit/NSColor/brightnessComponent)

The brightness component value of the color.

[`catalogNameComponent`](/documentation/AppKit/NSColor/catalogNameComponent)

The catalog containing the color’s name.

[`localizedCatalogNameComponent`](/documentation/AppKit/NSColor/localizedCatalogNameComponent)

The localized version of the catalog name containing the color.

[`colorNameComponent`](/documentation/AppKit/NSColor/colorNameComponent)

The name of the color.

[`localizedColorNameComponent`](/documentation/AppKit/NSColor/localizedColorNameComponent)

The localized version of the color name.

### Working with the color space

[`type`](/documentation/AppKit/NSColor/type)

The type of the color object.

[`usingType(_:)`](/documentation/AppKit/NSColor/usingType(_:))

Returns a version of the color object that is compatible with the specified color type.

[`NSColor.ColorType`](/documentation/AppKit/NSColor/ColorType)

Constants that indicate the color’s type, and which methods may be called on the color object.

[`colorSpace`](/documentation/AppKit/NSColor/colorSpace)

The color space associated with the color.

[`NSColorSpaceName`](/documentation/AppKit/NSColorSpaceName)

Constants that specify color space names.

### Supporting high dynamic range (HDR) colors

[`linearExposure`](/documentation/AppKit/NSColor/linearExposure)

For HDR colors, the linear brightness multiplier that was applied when generating the color. Colors created with an exposure by NSColor create CGColors that are tagged with a contentHeadroom value. While CGColors created without a contentHeadroom tag will return 0 from CGColorGetHeadroom, NSColors generated in a similar fashion return a linearExposure of 1.0.

[`standardDynamicRange`](/documentation/AppKit/NSColor/standardDynamicRange)

In some cases it is useful to recover the color that was base the SDR color that was exposed to generate an HDR color. If a color’s `linearExposure` is > 1, then this will return the base SDR color. If the color is not an HDR color, this will return `self`.

[`applyingContentHeadroom(_:)`](/documentation/AppKit/NSColor/applyingContentHeadroom(_:))

Reinterpret the color by applying a new `contentHeadroom` without changing the color components. Changing the `contentHeadroom` redefines the color relative to a different peak white, changing its behavior under tone mapping and the result of calling `standardDynamicRangeColor`. The new color will have a `contentHeadroom` >= 1.0. If called on a color with a color space that does not support extended range, or does not have an equivalent extended range counterpart, this will return `self`.

### Retrieving core graphics color information

[`cgColor`](/documentation/AppKit/NSColor/cgColor)

The Core Graphics color object corresponding to the color.

### Drawing with colors

[`drawSwatch(in:)`](/documentation/AppKit/NSColor/drawSwatch(in:))

Draws the current color in the specified rectangle.

[`set()`](/documentation/AppKit/NSColor/set())

Sets the color of subsequent drawing to the color that the color object represents.

[`setFill()`](/documentation/AppKit/NSColor/setFill())

Sets the fill color of subsequent drawing to the color object’s color.

[`setStroke()`](/documentation/AppKit/NSColor/setStroke())

Sets the stroke color of subsequent drawing to the color object’s color.

### Determining when colors change

[`systemColorsDidChangeNotification`](/documentation/AppKit/NSColor/systemColorsDidChangeNotification)

Sent when the system colors have changed, such as through a system control panel interface.

### Getting the standard grayscale colors

[`NSWhite`](/documentation/AppKit/NSWhite)

A constant that specifies the white shade in the 2-bit deep grayscale color space.

[`NSLightGray`](/documentation/AppKit/NSLightGray)

A constant that specifies the light gray shade in the 2-bit deep grayscale color space.

[`NSDarkGray`](/documentation/AppKit/NSDarkGray)

A constant that specifies the dark gray shade in the 2-bit deep grayscale color space.

[`NSBlack`](/documentation/AppKit/NSBlack)

A constant that specifies the black shade in the 2-bit deep grayscale color space.

### Supporting old versions of AppKit

[`NSAppKitVersionNumberWithPatternColorLeakFix`](/documentation/AppKit/NSAppKitVersionNumberWithPatternColorLeakFix)

The specific version of the AppKit framework from OS X 10.1 that correctly autoreleases color objects.

### Deprecated

[`ignoresAlpha`](/documentation/AppKit/NSColor/ignoresAlpha)

A Boolean value that indicates whether the app supports alpha.

[`colorSpaceName`](/documentation/AppKit/NSColor/colorSpaceName)

The name of the color space associated with the color.

[`usingColorSpaceName(_:)`](/documentation/AppKit/NSColor/usingColorSpaceName(_:))

Creates a new color object whose color is the same as the receiver’s, except that the new color object is in the specified color space.

[`usingColorSpaceName(_:device:)`](/documentation/AppKit/NSColor/usingColorSpaceName(_:device:))

Creates a new color object for the same color, but in the specified color space and specific to the provided device.

[`currentControlTintDidChangeNotification`](/documentation/AppKit/NSColor/currentControlTintDidChangeNotification)

Sent after the user changes control tint preference.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)