Back to blog

Working with Assets Catalogs in Xcode

Aasif Khan
By Aasif Khan | Last Updated on January 26th, 2024 7:37 am | 4-min read

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

Describe your app idea
and AI will build your App

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:

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:

  • On the left, the Outline, which shows every asset in the catalog

  • In the middle, the editor itself, i.e. a display of images, colors, etc.

  • 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:

  • The App Icon (shown above), which is an assortment of square images in different sizes (more on sizes later!)

  • Images, usually PNGs or JPGs, in different 1x, 2x, etc. image scales

  • Colors, which are effectively color codes like #00DC98 linked to a name, like “mint-green”

  • 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!

    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:

    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
    Image(“lolcatz”)
    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 [email protected] and [email protected] 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

      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.

      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


      Related Articles

      Aasif Khan

      Head of SEO at Appy Pie

      App Builder

    Most Popular Posts