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

# NSImage.SymbolConfiguration

An object that contains the specific font, style, and weight attributes to apply to a symbol image.

```
class SymbolConfiguration
```

## Overview

Symbol image configuration objects include details such as the point size, scale, text style, and weight to apply to your symbol image. The system uses these details to determine which variant of the image to use and how to scale or style the image.

```swift
if let image = NSImage(systemSymbolName: "multiply.circle.fill",
                       accessibilityDescription: "A multiply symbol inside a filled circle.") {
        
    var config = NSImage.SymbolConfiguration(textStyle: .body,
                                                     scale: .large)
    config = config.applying(.init(paletteColors: [.systemTeal, .systemGray]))
    imageView.image = image.withSymbolConfiguration(config)
}
```

[`NSImage.SymbolConfiguration`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class) objects are immutable after you create them. If you use the [`applying(_:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/applying(_:)) method on the object, the new image attributes replace any previous attributes you supplied. After creating a symbol configuration object, assign it to the [`symbolConfiguration`](/documentation/AppKit/NSImageView/symbolConfiguration) property of the [`NSImageView`](/documentation/AppKit/NSImageView) object you use to display the image. If you draw the image directly, use the [`withSymbolConfiguration(_:)`](/documentation/AppKit/NSImage/withSymbolConfiguration(_:)) method to create a new image that contains the new attributes.

For design guidance, see [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/sf-symbols/overview/).

## Topics

### Creating a Symbol Configuration

[`init(pointSize:weight:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(pointSize:weight:))

Creates a symbol configuration with the specified point size and font weight.

[`init(pointSize:weight:scale:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(pointSize:weight:scale:))

Creates a symbol configuration with the specified point size, font weight, and symbol scale.

[`init(textStyle:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(textStyle:))

Creates a symbol configuration with the specified text style.

[`init(textStyle:scale:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(textStyle:scale:))

Creates a symbol configuration with the specified text style and symbol scale.

[`init(scale:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(scale:))

Creates a symbol configuration using the scale you specify.

[`init(colorRenderingMode:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(colorRenderingMode:))

Create a configuration with a specific color rendering mode.

[`init(variableValueMode:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(variableValueMode:))

Create a configuration with a specified variable value mode.

[`NSFont.TextStyle`](/documentation/AppKit/NSFont/TextStyle)

Constants that specify the preferred text styles you use with fonts.

[`NSImage.SymbolScale`](/documentation/AppKit/NSImage/SymbolScale)

Constants that specify which scale variant of a symbol image to use.

[`NSImage.SymbolColorRenderingMode`](/documentation/AppKit/NSImage/SymbolColorRenderingMode)

[`NSImage.SymbolVariableValueMode`](/documentation/AppKit/NSImage/SymbolVariableValueMode)

### Applying a Configuration

[`applying(_:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/applying(_:))

Creates a configuration object by applying the values from the configuration you specify.

### Creating a Color Configuration

[`init(paletteColors:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(paletteColors:))

Creates a color configuration by specifying a palette of colors.

[`init(hierarchicalColor:)`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/init(hierarchicalColor:))

Creates a hierarchical color configuration using the color you specify.

[`preferringMulticolor()`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/preferringMulticolor())

Creates a configuration that specifies that the symbol should prefer its multicolor variant if one exists.

### Type Methods

[`preferringHierarchical()`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/preferringHierarchical())

Creates a configuration that specifies that the symbol should prefer its hierarchical variant, if one exists.

[`preferringMonochrome()`](/documentation/AppKit/NSImage/SymbolConfiguration-swift.class/preferringMonochrome())

Creates a configuration that specifies that the symbol should prefer its monochrome variant.


---

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)