Article

Creating Custom Symbol Images for Your App

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

Overview

SF Symbols is a set of over 1,500 symbol images created by Apple that you can use as icons in your app. While symbol images are images, you can apply traits typically associated with text. For example, you can apply a tint color, font text style, weight, or scale to integrate them seamlessly with surrounding text.

If you need custom iconography in your app, create custom symbol images with the same capabilities as the ones in SF Symbols:

  • Export an SVG file from the SF Symbols app.

  • Open the SVG file in a vector-drawing app, use it as a template to create your custom iconography, and export it as an SVG file.

  • Use your custom symbol image in your app like one that’s part of SF Symbols.

Export a Custom Symbol Template File

To create an SVG file for your custom symbol image, export a custom symbol template file from the SF Symbols app:

  1. Download the SF Symbols app and install it on your Mac.

  2. Launch the app and select a symbol image similar to the one you want to create.

  3. Choose File > Export Symbol…, and save the resulting SVG file.

  4. Open the exported SVG file, or custom symbol template, in a vector-drawing app such as Adobe Illustrator or Sketch, and use it as a starting point to create your custom symbol image.

  5. Expand all layers and examine the names of all layers and groups. Retain their exact identifiers, and adhere to the requirements outlined in this article to be able to use your custom symbol image in Xcode.

Creating a custom symbol image doesn’t require you to maintain and edit multiple files. All variants of a symbol image are part of a single SVG file with uniquely named SVG nodes.

In addition to different variants of the symbol image, the SVG file contains guides to align the symbol image with text, as well as annotations and meta information. The guides and information show up as a layer or shape with a unique name if you open the SVG file in a vector-drawing application.

Manage Symbol Image Variants

The Symbols layer contains 27 child layers, each representing a symbol image variant.

An illustration that shows an abstract representation of the different layers in a custom symbol template file. The Symbols layer is expanded, showing the Regular-M object. It contains the optional groups, such as Ultralight-M or Thin-S, with dotted outlines to indicate that they are note required.

As you create your custom symbol image, make sure the layout of the Symbol layer conforms to the following requirements:

  • Each symbol image variant must be a group, and can contain any number of shapes, but no other object types.

  • Don’t use text or bitmap images.

  • Transforms of shapes are optional but respected.

It’s not necessary for a template to contain all 27 variants. While only the Regular-M variant is required, it’s a good idea to create the Regular-S/-M/-L and Semibold-S/-M/-L variants because a lot of common UIKit controls and accessibility features like Bold Text use them.

Identifiers of symbol variants have the form <weight>-<{S, M, L}> , where weight corresponds to a weight of the San Francisco system font and S, M, or L matches the small, medium, or large font scale. Use the following identifiers for each variant:

Ultralight-S

Ultralight-M

Ultralight-L

Thin-S

Thin-M

Thin-L

Light-S

Light-M

Light-L

Regular-S

Regular-M

Regular-L

Medium-S

Medium-M

Medium-L

Semibold-S

Semibold-M

Semibold-L

Bold-S

Bold-M

Bold-L

Heavy-S

Heavy-M

Heavy-L

Black-S

Black-M

Black-L

Organize the Guides Layer

The operating system uses guides to align your custom symbol image with surrounding text. For example, it uses the provided baseline and cap height information for each of the three font scales (small, medium, and large) to compute the symbol image’s baseline offset and cap height.

The template file contains all necessary guides in the Guides layer; you don’t need to modify them. In case of accidental changes, restore the guides to meet the following requirements:

  • A symbol template file must contain three sets of guides for the baseline and capline, one for each font scale.

  • Baseline and capline guides must be either a line or path shape.

  • A symbol template file must contain two guides to indicate the leading and trailing symbol margins, which indicate how much whitespace precedes and follows the symbol image when it appears in text.

  • The guides for leading and trailing margin need to be rectangular shapes.

The guides’ identifiers must match the following identifiers:

Capline-S

Capline-M

Capline-L

Baseline-S

Baseline-M

Baseline-L

left-margin

right-margin

The Guides layer also contains an uppercase letter A in outline form for each scale in the SF Text font as a reference glyph. Use the reference glyphs in the template as guides for how a symbol image looks next to text.

An illustration that shows an abstract representation of the different layers in a custom symbol template file. The Guides layer is expanded, showing all if its child objects.

For design purposes, the SF Symbols app typesets the template file at a particular point size, usually 100 points. The operating system scales them to the requested point size when used in an app.

Create Your Custom Symbol Image

Start creating your own custom symbol image by modifying the SF Symbol in the exported custom symbol template file. You can use the file for cues to line weight and other attributes for your custom symbol image. Begin with the Regular-M variant, then add the small and large scale variants for the Regular weight.

Use the following scale factors:

<weight>-S

<weight>-M

<weight>-L

Scale Factor

0.783

1.0

1.29

Once you finish creating the scale variants for the Regular weight, add support for the other symbol image variants.

It’s important to position your custom symbol using the provided guides to make sure that it appears correctly in text. Position a symbol image relative to its capline and baseline guides. As the operation system reads a symbol image, the distance (either positive or negative) from the bottom edge of the symbol to its baseline becomes the baselineOffsetFromBottom of the symbol. When the symbol image appears in text, the operating system positions it vertically so that the bottom edge of the symbol image is the same distance, scaled by point size, as the symbol image was from the baseline guide in the template file.

An illustration of the leading and trailing margin, as well as the capline and baseline offsets. It shows one of the symbol images provided and the guides for margins and offsets.

The widths of the margin guides determine the leading and trailing margins of all variants in the custom symbol template. You only need to define the leading and trailing margin guides once and not for each individual variant. Their vertical and horizontal positioning of the margin guides isn’t important, but the convention is to place them to either side of the Regular-M symbol image variant.

Preserve Annotations and Meta Information in the Notes Layer

The Notes layer contains optional annotations and meta information about the template file:

  • The template-version layer contains a version string that indicates the template format version that you exported from the SF Symbols app. Xcode may use it in the future to distinguish different versions of the custom symbol template file format and must be a text layer.

  • The artboard layer makes sure design tools display the template with a convenient canvas size and legible symbols.

The Notes layer includes annotations on the custom symbol template file that can help you understand its contents. These annotations are optional, but it’s a good idea to keep them as-is.

Export Your Custom Symbol and Preserve All Names

When you finish editing your symbol in the custom symbol template, re-export it as an SVG file with maximum precision. Confirm that the SVG file preserves all identifiers for different symbol variants and guides, and matches the identifiers outlined above.

Verify your SVG file by adding it to an asset catalog in your Xcode project. Create a new Symbol Image Set asset, and drag the SVG file into that asset. Xcode verifies the SVG file and displays error messages in case your SVG file doesn’t conform to the requirements.

You can verify the contents of the SVG file manually, as well. Open it as an XML file in Xcode by selecting the SVG file in Xcode’s project navigator, control-click on the file, and select Open As > Source Code. The following code listing shows that the vector-drawing app preserved all identifiers when the user exported their custom symbol image. In an actual file, each item’s XML node contains additional information such as transforms or paths that have been omitted from the code snippet for better readability.

Note how the XML nodes have id properties that match with those of the Guides and Symbols layers in the vector-drawing app.

<g id="Guides">
<!--- Other XML properties, such as transforms, H-reference, and so on will be placed here, too. -->
    <line id="Baseline-S" class="st7" x1="263" y1="696" x2="3036" y2="696"/>
    <line id="Capline-S" class="st7" x1="263" y1="625.5" x2="3036" y2="625.5"/>
    <!-- ... -->
    <rect id="left-margin" x="1391.3" y="1030.8" class="st5" width="8.7" height="119.3"/>
    <rect id="right-margin" x="1499.7" y="1030.8" class="st5" width="8.7" height="119.3"/>
</g>
<g id="Symbols">
<!--
Each symbol node can contain any number of shapes and paths but no other items;
text or custom items are not allowed. Transforms of shapes are optional but will be respected.
-->
    <g id="Ultralight-S" transform="matrix(1 0 0 1 515.644 696)">
        <path d="M44,2.1c20.5,0,37.3-16.7,37.3-37.2c0-20.5-16.8-37.2-37.3-37.2S6.8-55.6,6.8-35.2C6.8-14.7,23.6,2.1,44,2.1z M30.5-16.9
C23-16.9,18-24.3,18-35.3S23-53.6,30.5-53.6c7.4,0,12.5,7.4,12.5,18.4S37.9-16.9,30.5-16.9z M59.8-16.8c-5.8,0-10.2-3.1-11.1-7.4
c0-0.2-0.1-0.5-0.1-0.7c0-0.6,0.4-1.1,1.1-1.1c0.6,0,1,0.3,1.1,1c1,3.4,4.7,6,9.3,6c5.5,0,9.5-4.1,9.5-9.6c0-5.6-3.8-9.4-9.3-9.4
c-3.2,0-5.7,1-8.3,4.2c-0.5,0.5-0.8,0.6-1.4,0.6c-0.9,0-1.4-0.6-1.3-1.5l1.3-16.7c0.1-1.1,0.7-1.7,1.7-1.7h16.9
c0.6,0,1.1,0.5,1.1,1.2c0,0.6-0.4,1.1-1.1,1.1H52.8L51.6-36h0.2c2-2.6,5.4-4.2,8.8-4.2c6.6,0,11.4,4.8,11.4,11.5
C72-21.6,67-16.8,59.8-16.8z M30.5-19.1c6.1,0,10.1-6.5,10.1-16.1s-4.1-16.2-10.1-16.2c-6,0-10.1,6.6-10.1,16.2
S24.5-19.1,30.5-19.1z"/>
    </g>
    <g id="Thin-S" transform="matrix(1 0 0 1 811.867 696)">
        <!-- ... -->
    </g>
    <g id="Light-S" transform="matrix(1 0 0 1 1107.6 696)">
        <!-- ... -->
    </g>
    <g id="Regular-S" transform="matrix(1 0 0 1 1403.58 696)">
        <!-- ... -->
    </g>
    <g id="Medium-S" transform="matrix(1 0 0 1 1699.7 696)">
        <!-- ... -->
    </g>
    <g id="Semibold-S" transform="matrix(1 0 0 1 1995.98 696)">
        <!-- ... -->
    </g>
    <!-- Each symbol image variant is represented as its own XML node. -->
    <!-- ... -->
    <g id="Black-L" transform="matrix(1 0 0 1 2854.08 1556)">
        <!-- ... -->
    </g>
</g>

Use Your Custom Symbol Image

Open your app’s Xcode project and select its asset catalog. In Xcode’s menu bar, select Editor > Add Assets > New Symbol Image Set, and drag your exported SVG file into the Symbol SVG section of the Symbol Image pane. Xcode validates the SVG file, and displays error messages if the file doesn’t fulfill the requirements. To use the symbol image in your app, follow Configuring and Displaying Symbol Images in Your UI.

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.

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.

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.

Beta
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.

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

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

Beta
init?(systemName: String)

Creates an image object containing a system symbol image.

Beta