Working with Assets Catalogs in Xcode

Written by Reinder de Vries on August 20 2020 in App Development, iOS

Working with Assets Catalogs in Xcode

Assets catalogs are super useful to organize your app’s assets in Xcode. Drop graphics, images, icons, colors and vectors into an asset catalog and use them directly in your app’s code.

In this tutorial, we’re going to discuss:

  • How to add colors and images to an asset catalog
  • How you use asset catalogs in practical iOS development
  • Different sizes and scales for images
  • Using colors with Dark and Light Mode
  • How to use colors and images from an asset catalog in your code

Ready? Let’s go.

  1. The Assets.xcassets Catalog in Xcode
  2. Working with Image Assets
  3. Working with Color Assets
  4. Further Reading

The Assets.xcassets Catalog in Xcode

An asset catalog, simply put, is a single folder in Xcode that you use to organize your app’s images, icons, colors, and more. Instead of adding individual images to Xcode’s file organizer, you add assets neatly organized in a single catalog. Asset catalogs also include metadata, for example about image scale.

Here’s an example Assets.xcassets asset catalog in an Xcode project:

Xcode Asset Catalog

An app project in Xcode has one default .xcassets catalog by default, which you can find in the Project Navigator on the left of Xcode. When you open it, you see the following UIs:

  1. On the left, the Outline, which shows every asset in the catalog
  2. In the middle, the editor itself, i.e. a display of images, colors, etc.
  3. On the right, Xcode’s Inspectors, most notably the Attributes Inspector

The most common asset types in a run-of-the-mill app project are:

  1. The App Icon (shown above), which is an assortment of square images in different sizes (more on sizes later!)
  2. Images, usually PNGs or JPGs, in different 1x, 2x, etc. image scales
  3. Colors, which are effectively color codes like #00DC98 linked to a name, like “mint-green”
  4. SVGs (Xcode 12+), i.e. vector graphics, which are useful for single-scale graphics assets and images

What are advantages of using a asset catalog in your app project?

  • Most functions and components in the iOS SDKs that deal with assets can directly work with the asset’s name, i.e. Color("green") and Image("logo"), which is super convenient. You can even use image and color literals in Xcode’s editor, so icons and colors show up as inline images.
  • When you use assets catalogs, the App Store can use App Thinning to only download relevant images and assets to a user’s iPhone. For example, the bigger iPhone 11 Pro doesn’t need to store low-res 1x images. This reduces the app download and subsequent storage size.
  • An asset catalog contains all sorts of useful metadata on assets, such as their intended platform, scale, color space, light/dark mode, LTR/RTL direction, and so on. This allows you to finetune assets in your app and provide a better experience to your app’s users.

Let’s find out more about the specifics of assets in Xcode!

An .xcassets file is, in fact, a folder inside your Xcode project’s root folder. Assets are stored in subfolders and metadata is stored in JSON files. That’s all quite compatible with version control tools like Git. Neat!

Learn how to build iOS apps

Get started with iOS 13 and Swift 5

Sign up for my iOS development course, and learn how to build great iOS 13 apps with Swift 5 and Xcode 11.

Working with Image Assets

The most common assets you’ll find in an asset catalog are, of course, images! You use them for all sorts of things: photos, icons, graphics, vectors, and so on. Anything that’s pixely and cannot be drawn with graphics code alone, is probably going to be a PNG or JPG image file.

Adding an image to an asset catalog is as simple as dragging it from Finder to Xcode. Like this:

Adding images to asset catalog in Xcode

Once you’ve added an image to the asset catalog, you can use ’em in your code like this:

// UIKit
imageView.image = UIImage(named: "lolcatz")

// SwiftUI

Simple, right? An advantage of working with the default asset catalog in Xcode is that you can reference the name of the asset directly in your code. You don’t need to load a bundle, read from a file or work with filepaths.

If you look closely at the above screenshot, you’ll see that we’re actually dragging 3 files from Finder to Xcode. What’s up with that? It’s because of different iPhone screen sizes, in short.

Different iPhone models have a different absolute screen sizes and resolutions, which results in a distinct pixels-per-inch (PPI) for that iPhone. When you can fit more pixels in the same “physical” space, you need bigger images. You provide those images in your iOS app through Xcode, with the filename@2x.png and filename@3x.png file naming convention.

By the way, the App Icon asset in the Assets.xcassets file looks complicated, but it’s just an image. The difference with an ordinary image asset is that the app icon contains images with lots of different sizes. Each size corresponds to a specific iPhone/iPad model and use case, like @3x for an iPhone notification icon. When you’re configuring your app’s icon, just export the image file to the different sizes (or use a template), drag-and-drop them into the appropriate slots, and you’re done.

You can learn more about image scaling and pixels vs. points in this tutorial: 1x, 2x and 3x Image Scaling on iOS Explained

You generally use 1 of 3 image file types in your iOS app:

  1. PNG: A lossless, compressed file format that supports transparency. Use it for vectors, icons and illustrations. You can choose between PNG-8 and PNG-24 to reduce the filesize further.
  2. JPG: A lossy, compressed file format that does not support transparency. Use it for complex graphics, bitmaps and photos. JPG has better compression compared to PNG, but it also loses more color and bitmap data.
  3. SVG: Since Xcode 12 you can use Scalable Vector Graphics, which is an XML-based format for vector images like icons, graphs and illustrations. When used in conjunction with text compression and optimization, it’s often smaller than PNG. It’s also scale-independent, which means you won’t need 2-3 images for different screen sizes.

If you want to keep the download and storage size of your app small, it’s smart to use a tool like ImageOptim to optimize your images prior to importing them into Xcode. You can drastically reduce the size of your image asset files, depending on the settings you choose.

Awesome! Let’s get back to the asset catalog, and discuss color assets next.

Author’s Note: You can also add PDFs (scale-independent) to your app’s asset catalog in Xcode, but there’s no need for that anymore now that SVG is here.

Working with Color Assets

An underappreciated feature of Xcode asset catalogs is the ability to add colors directly to the catalog. You can define RGB colors and use them in your app by name, just like you would an image.

Here’s how that works:

  1. Open the asset catalog in Xcode
  2. Right-click in the Outline on the left
  3. Choose New Color Set
  4. Select the color in the editor (“Universal”)
  5. Navigate to the Attributes Inspector on the right
  6. Change the color’s RGB properties, for example, to a hex color code

Colors in Xcode asset catalog

How do you use the color in your app? Here’s how:

// SwiftUI
Text("So long and thanks for all the fish").foregroundColor(Color("mint"))

// UIKit
textLabel.textColor = UIColor(named: "mint")

A few things to keep in mind:

  • Use the sRGB (or DCI-P3) color space to set your colors. This is the color space that iOS uses on iPhone and iPad. Make sure to set your graphics editing tool (i.e., Sketch) and your computer monitor to the same color space.
  • When changing the color in the asset catalog, you can choose between input as hex color codes, or values between 0-255 and 0.0-1.0. It’s easiest to use hex color codes, because you can usually copy-and-paste them directly from your graphics editing tool. You can also use the macOS Color Panel.

Working with colors via the Xcode asset catalog has another interesting benefit: you can automatically add colors to support Dark Mode. Here’s how that works:

  • With your color selected, change the Appearances setting in the Attribute Inspector. You can change it to support 3 different appearances:
    • None: The color won’t change its appearance.
    • Any, Dark: Any is used for Light Mode and older iOS versions that don’t support Dark Mode. Dark is of course used for Dark Mode.
    • Any, Dark, Light: Any is used for older iOS versions that don’t support Dark/Light Mode appearances. Dark and Light are used for Dark and Light Mode, respectively.

One of the cool things about this setting is that it changes the colors in your app effortlessly between Dark and Light modes. If you use the color name consistently in your app, you should be able to adopt Dark Mode with almost zero effort.

This same Appearances setting also works for images, of course. You can specify which image file to use when, i.e. use a specific image for Dark Mode.

Learn how to build iOS apps

Get started with iOS 13 and Swift 5

Sign up for my iOS development course, and learn how to build great iOS 13 apps with Swift 5 and Xcode 11.

Further Reading

Awesome! Now you know how useful asset catalogs in Xcode are. You can store all sorts of things in them: images, colors, metadata, and much more. Here’s what we discussed:

  • How you use asset catalogs in practical iOS development
  • How to add colors and images to an asset catalog
  • Using colors with Dark and Light Mode
  • Different sizes and scales for images
  • How to use colors and images from an asset catalog in your code

Want to learn more? Check out these resources:

Reinder de Vries

Hi, I'm Reinder.
I help developers play with code.

Get the Weekly

Get iOS/Swift tutorials and insights in your inbox, every Monday.
  • This field is for validation purposes and should be left unchanged.

Most Popular

Browse Topics

Swift Sandbox

Code Swift right in your browser!
Go to the Swift Sandbox

Reinder de Vries

Reinder de Vries

Reinder de Vries is a professional iOS developer. He teaches app developers how to build their own apps at Since 2009 he has developed a few dozen apps for iOS, worked for global brands and lead development at several startups. When he’s not coding, he enjoys strong espresso and traveling.


Build great iOS apps
Learn how in my free 7-day course

  • This field is for validation purposes and should be left unchanged.

No spam, ever. Unsubscribe anytime. Privacy Policy