Article

Configuring and Displaying Symbol Images in Your UI

Create scalable images that integrate well with your app’s text, and adjust the appearance of those images dynamically.

Overview

Symbol images give you a consistent set of icons to use in your app, and ensure that those icons adapt to different sizes and to app-specific content. A symbol image contains a vector-based shape that scales without losing its sharpness. Like you do with a template image, you apply a tint color to that shape to generate its final appearance in your app. You use template images in places where you display a simple shape or glyph, such as a bar button item.

Although symbol images are images, they also support many traits typically associated with text. In fact, many of the system symbol images include letters, numbers, or symbolic characters in their content. For example, the system provides symbol images for mathematical operators for addition, subtraction, multiplication, and division. You can also apply text-related traits to a symbol image to make it look similar to the surrounding text:

  • Apply a font text style to a symbol image so that it matches text with the same style. Font text styles also cause symbol images to scale to match the current Dynamic Type setting.

  • Apply weights, such as thin, heavy, or bold, to a symbol image.

  • Scale and style symbol images to match the font you use for text.

  • Align a symbol image with neighboring text by using the image’s baseline.

The system provides a collection of standard symbol images for you to use, including images for folders, the trash can, favorite items, and many more. Symbol images also adapt automatically to the current trait environment, reducing the work required to support differently sized interfaces. To browse the available symbol images, use the SF Symbols app, which you can download from the design resources page at developer.apple.com.

You can also create symbol image files for your app’s custom iconography, as described in Creating Custom Symbol Images for Your App.

Load a Symbol Image

To load a symbol image, you must know its name. When configuring an image view in a storyboard file, you can browse the list of symbol image names in the Attribute inspector. When loading symbol images from your code, look up the name for any system symbol images using the SF Symbols app. For custom symbol images, create a Symbol Image Set asset in your asset catalog and load the asset by name.

UIKit provides different paths for loading symbol images, based on whether the system provides the image or you do:

Each method looks only for its designated image type, which avoids namespace collisions between your custom images and the system images. The following example code loads the multiply.circle.fill system symbol image:

let image = UIImage(systemName: "multiply.circle.fill")

Apply a Specific Appearance to a Symbol Image

When you use the init(systemName:) or init(named:) method, UIKit returns an image object with the symbol image information. When you display that symbol image in an image view, the system applies default styling to it. An image with the default styling might appear out of place next to bold text or text that uses the headline text style.

To make the symbol image blend in with the rest of your content, create a UIImage.SymbolConfiguration object with information about how to style the image. Configure the object with the text style you use for neighboring labels and text views, or specify the font you use in those views. You can add weight information to give the symbol image a thinner or thicker appearance. You can also specify whether you want the image to appear slightly larger or smaller than the neighboring text.

Assign your configuration data to the preferredSymbolConfiguration property of the UIImageView containing your symbol image. Typically, you apply configuration data only to image views. For other types of system views, UIKit typically provides configuration data based on system requirements. For example, bars configure the symbol images in their bar button items to match the bar’s configuration. The only other time you might use configuration data is when drawing the image directly. In that case, use the applyingSymbolConfiguration(_:) method to create a version of your image that includes the specified configuration data.

Align Symbol Images with a Text Label by Using a Baseline

When positioning an image view containing a symbol image next to a label, you can align the views using their baselines. To align views in your storyboard, select the two views and add a First Baseline constraint. Programmatically, you create this constraint by setting the firstBaselineAnchor of both views to be equal, as shown in the following code example:

NSLayoutConstraint.activate([
   imageView!.firstBaselineAnchor.constraint(equalTo: label!.firstBaselineAnchor)
])

All system-provided symbol images include baseline information, and UIImage exposes the baseline value as an offset from the bottom of the image. Typically, the baseline of a symbol image aligns with the bottom of any text that appears in the image, but even symbol images without text have a baseline. In addition, you can add a baseline to any image by calling its withBaselineOffset(fromBottom:) method. The following code example loads an image and adds a baseline 2.0 points up from the bottom of the image.

let image = UIImage(named: "MyImage")
let baselineImage = image?.withBaselineOffset(fromBottom: 2.0)

See Also

Loading and Caching Images

Providing Images for Different Appearances

Supply image resources that work for light and dark appearances and for high-contrast environments.

Creating Custom Symbol Images for Your App

Create symbol images and expand on the icons provided by SF Symbols.

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

Creates an image object using the named image asset that is compatible with the specified trait collection.

init?(named: String, in: Bundle?, with: UIImage.Configuration?)

Creates an image object using the named image asset that is compatible with the specified configuration.

init?(named: String)

Creates an image object from the specified named asset.

init(imageLiteralResourceName: String)

Returns the image object associated with the specified resource.

init?(systemName: String, withConfiguration: UIImage.Configuration?)

Creates an image object containing a system symbol image with the specified configuration.

init?(systemName: String, compatibleWith: UITraitCollection?)

Creates an image object containing a system symbol image appropriate for the specified traits.

init?(systemName: String)

Creates an image object containing a system symbol image.