Skip to content

UIImage.imageNamed() static method ​

The UIImage.imageNamed() static method gets an image from the app bundle by name.

Syntax ​

UIImage.imageNamed(name)

Parameters ​

name

A string. The image's path in the app bundle, starting from the bundle's root; the extension can be omitted. Non-strings are converted with String().

Files in the project's assets/ directory are at JS/assets/ in the app bundle, so assets/logo.png is written 'JS/assets/logo'.

Return value ​

A UIImage. Returns null when not found, rather than throwing.

Exceptions ​

None.

Description ​

Lookup rules (measured):

  • Without an extension, only .png files are looked up. To get GIF or WebP animated images, include the extension in the name, such as 'JS/assets/anim.gif'. APNG uses the .png extension, so it can be omitted.
  • Subdirectories aren't searched recursively. If the image is in JS/assets/, writing 'logo' doesn't find it.
  • @2x and @3x files are selected automatically even in subdirectories. When a directory has dot.png, dot@2x.png, and dot@3x.png, the system picks one for the screen; don't write @2x or @3x in the name.
  • When the file is an animated image, you get an animated image; see Animated images.

iOS has another way to store images, called an Asset Catalog. It is the image library Xcode manages, compiled into a single Assets.car file. imageNamed() looks in the Asset Catalog first, then in files in the app bundle. When both have an image with the same name, the Asset Catalog one is used (not verified in the simulator).

Projects generated by the command-line tool currently have no way to add images to the Asset Catalog: the generated ios/ directory is rebuilt every time, and its Asset Catalog contains only the app icon. So images go into assets/ as ordinary files. The comparison below applies to apps with a hand-maintained Xcode project:

In an Asset CatalogAs ordinary files
Found by imageNamed()YesYes
Automatic @2x / @3x selectionYesYes
Automatic image switch in dark modeYesNo
Per-device app thinning, on-demand downloadYesNo
File path and bytes availableNoYes
WebP supportNo, compilation failsYes
  • After compilation, an Asset Catalog no longer contains separate image files. Don't put images there that you need to upload, hash, or pass to other APIs.
  • WebP images can't go into an Asset Catalog. Once one is in, the whole Asset Catalog fails to compile.

Examples ​

js
UIImage.imageNamed('logo');              // Finds logo.png at the root of the app bundle
UIImage.imageNamed('JS/assets/logo');    // Finds an image in a subdirectory; write the path in the name
UIImage.imageNamed('logo.png');          // Including the extension also works

Result: All three forms get the image.

js
const dot = UIImage.imageNamed('JS/assets/dot');
if (dot) {
  console.log(dot.size.width, dot.size.height, dot.scale);
}

Result: On a device with a @3x screen, the console prints 10 10 3.

Corresponding iOS API ​

+[UIImage imageNamed:]. The native method gives only the first frame of an animated image file; here you get an animated image.

See also ​