Create scalable images that integrate well with your app’s text, and adjust the appearance of those images dynamically.
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:
Load your app’s custom symbol images using the
Named: in Bundle: compatible With Trait Collection:
Named: in Bundle: with Configuration:
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 system symbol image:
Apply a Specific Appearance to a Symbol Image
When you use the
image 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
UIFont text style.
To make the symbol image blend in with the rest of your content, create a
UIImage 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
preferred property of the
UIImage 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
image 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
first of both views to be equal, as shown in the following code example:
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
image method. The following code example loads an image and adds a baseline
2 points up from the bottom of the image.