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


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



The name of the image asset or file. For images in asset catalogs, specify the name of the image asset. For PNG images, you may omit the filename extension. For all other file formats, always include the filename extension.


The bundle containing the image file or asset catalog. Specify nil to search the app’s main bundle.


The image configuration that you want. Use this parameter to specify traits and other details that define which variant of the image you want. For example, when requesting a custom symbol image, you can specify whether you want the thin, regular, or bold image variant.

Return Value

An object containing the image variant that matches the specified configuration data, or nil if no suitable image was found.


When searching the asset catalog, this method checks first for an asset containing a symbol image, and then for an asset containing a bitmap image. Because symbol images are supported only in iOS 13 and later, you may include both types of assets in the same asset catalog. The system automatically falls back to the bitmap image on earlier versions of iOS. You cannot use this method to load system symbol images; use the init(systemName:withConfiguration:) method instead.

This method checks the system caches for an image with the specified name and returns the variant of that image that is best suited for the specified configuration. If a matching image object is not already in the cache, this method creates the image from an available asset catalog or loads it from disk. The system may purge cached image data at any time to free up memory. Purging occurs only for images that are in the cache but are not currently being used.

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.

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)

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.


Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software