From 310c9385cd357fd83bac7c6a15c6eb8ecdad0197 Mon Sep 17 00:00:00 2001 From: Janic Duplessis Date: Thu, 23 Jul 2026 09:02:42 -0400 Subject: [PATCH 1/2] Document the iOS asset catalog option for image assets --- docs/images.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/images.md b/docs/images.md index 0c547ebb34c..10362043c18 100644 --- a/docs/images.md +++ b/docs/images.md @@ -65,6 +65,21 @@ const icon = this.props.active Note that image sources required this way include size (width, height) info for the Image. If you need to scale the image dynamically (i.e. via flex), you may need to manually set `{width: undefined, height: undefined}` on the style attribute. +### Bundling images in an asset catalog (iOS) + +By default the bundler copies each required image, along with every `@2x` and `@3x` variant, into your iOS app as a loose file next to the JavaScript bundle. On iOS you can instead have them compiled into an [asset catalog](https://developer.apple.com/documentation/xcode/managing-assets-with-asset-catalogs), so the system ships and loads only the scale a device needs and resolves each image in a single named lookup. + +To opt in, set the `RCTUseAssetCatalog` key to `true` in your app's `Info.plist`: + +```xml +RCTUseAssetCatalog + +``` + +With this enabled, the iOS build script (`react-native-xcode.sh`) compiles your bundled images into an `RNAssets.bundle` asset catalog at build time, and the native image loader resolves them from it by name. Your `require('./my-icon.png')` calls stay exactly the same, and no changes to your Xcode project are needed. Apps that don't set the key are unaffected. + +After changing this setting, do a clean build. Incremental builds don't remove the image assets a previous build copied in with the other setting, so they would otherwise be shipped as unused dead weight. + ## Static Non-Image Resources The `require` syntax described above can be used to statically include audio, video or document files in your project as well. Most common file types are supported including `.mp3`, `.wav`, `.mp4`, `.mov`, `.html`, `.pdf` and more. See [bundler defaults](https://github.com/facebook/metro/blob/main/packages/metro-config/src/defaults/defaults.js#L16-L51) for the full list. From 369b17203dfac674dee6400fd3b5a85d12bb0527 Mon Sep 17 00:00:00 2001 From: Janic Duplessis Date: Thu, 23 Jul 2026 09:25:35 -0400 Subject: [PATCH 2/2] Update images.md --- docs/images.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/images.md b/docs/images.md index 10362043c18..0445967067d 100644 --- a/docs/images.md +++ b/docs/images.md @@ -67,7 +67,7 @@ Note that image sources required this way include size (width, height) info for ### Bundling images in an asset catalog (iOS) -By default the bundler copies each required image, along with every `@2x` and `@3x` variant, into your iOS app as a loose file next to the JavaScript bundle. On iOS you can instead have them compiled into an [asset catalog](https://developer.apple.com/documentation/xcode/managing-assets-with-asset-catalogs), so the system ships and loads only the scale a device needs and resolves each image in a single named lookup. +By default the bundler copies each required image, along with every `@2x` and `@3x` variant, into your iOS app as a loose file next to the JavaScript bundle. On iOS you can instead have them compiled into an [asset catalog](https://developer.apple.com/documentation/xcode/managing-assets-with-asset-catalogs), so the system ships only the scale a device needs. To opt in, set the `RCTUseAssetCatalog` key to `true` in your app's `Info.plist`: @@ -76,9 +76,9 @@ To opt in, set the `RCTUseAssetCatalog` key to `true` in your app's `Info.plist` ``` -With this enabled, the iOS build script (`react-native-xcode.sh`) compiles your bundled images into an `RNAssets.bundle` asset catalog at build time, and the native image loader resolves them from it by name. Your `require('./my-icon.png')` calls stay exactly the same, and no changes to your Xcode project are needed. Apps that don't set the key are unaffected. +With this enabled, the iOS build script compiles your bundled images into an `RNAssets.bundle` asset catalog at build time. Your `require('./my-icon.png')` calls stay exactly the same, and no changes to your Xcode project are needed. -After changing this setting, do a clean build. Incremental builds don't remove the image assets a previous build copied in with the other setting, so they would otherwise be shipped as unused dead weight. +After changing this setting, make sure to do a clean build. ## Static Non-Image Resources