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
.pngfiles 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.pngextension, so it can be omitted. - Subdirectories aren't searched recursively. If the image is in
JS/assets/, writing'logo'doesn't find it. @2xand@3xfiles are selected automatically even in subdirectories. When a directory hasdot.png,dot@2x.png, anddot@3x.png, the system picks one for the screen; don't write@2xor@3xin 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 Catalog | As ordinary files | |
|---|---|---|
Found by imageNamed() | Yes | Yes |
Automatic @2x / @3x selection | Yes | Yes |
| Automatic image switch in dark mode | Yes | No |
| Per-device app thinning, on-demand download | Yes | No |
| File path and bytes available | No | Yes |
| WebP support | No, compilation fails | Yes |
- 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
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 worksResult: All three forms get the image.
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
- Where bundled images go
imageWithContentsOfFile(): reading from an absolute path