fix(iOS): load header items icons synchronously when feasible

[johankasperi]

Description

When using RCTImageLoader for images in headerRightItems/headerLeftItems the asynchronous loadImageWithURLRequest produces som layout bugs as shown under "Screenshots". These are:

1. When setting title and image the title is briefly visible before the image is set.
2. When setting only image the bar button item is briefly shown as a very wide item without any content.

Changes

1. If the image is a ImageRequireSource load the image with [RCTConvert UIImage]. I know its deprecated but thats the only synchronous image loader that I know of.
2. If the image is a ImageURISource set the bar button title in the completion block of loadImageWithURLRequest
3. Updates BarButtonItems example to latest types/api from react-navigation/native-stack.

Screenshots / GIFs

Before

Title briefly shown

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-29.at.21.51.42.mov

Wide bar button item while loadImageWithURLRequest completes

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-29.at.22.19.46.mov

After

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-29.at.22.20.18.mov

Test code and steps to reproduce

Use any of the examples with required images in BarButtonItems

Checklist

• Included code example that can be used to test this change
• Updated TS types
• Updated documentation:
  • https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md
  • https://github.com/software-mansion/react-native-screens/blob/main/native-stack/README.md
  • https://github.com/software-mansion/react-native-screens/blob/main/src/types.tsx
  • https://github.com/software-mansion/react-native-screens/blob/main/src/native-stack/types.tsx
• Ensured that CI passes

[kkafar]

Yeah, we have this ugly effect now.

The situation here is a bit more complex.

First: in release mode, the code using RCTImageLoader will work just fine if we remove dispatch_async in completion block -> because this is the source of the delay.

In debug mode, when the assets are not loaded from application bundle (not talking about JS bundle here, rather NSBundle), but are downloaded from packager, RCTImageLoader does this asynchronously, indeed.

Since RCTConvert for image related conversions got deprecated, I'd like to limit its usage only for debug mode, where we can not load images synchronously in any other way. We could do this manually, but I'd like to avoid that option even more.

I'll start conversation with React Native team about giving us support for synchronous loading, since this will be rather a regression if the RCTConvert UIImage gets removed and we don't have any other sync API.

[kkafar]

Also disadvantage of using RCTConvert is that we don't have any image caching.

[kkafar]

I'm drafting a refactor & noticed this. Just a question.

[kkafar]

Why did you resign from setting title here and postponed it for later? Was there a particular reason here?

[johankasperi]

I didn't want to set the title before remote images had been downloaded

[johankasperi]

But shouldn't be needed anymore since from what I understand also remote images will be loaded synchronously in production mode?

[kkafar]

No, only assets stored on the device will be loaded synchronously. If you need to download header button images from some remote source during runtime (is this a valid use case?) it'll be done asynchronously. Packager (metro) assets are treated like device-local assets, so they're exception to that rule & will be loaded synchronously.

[johankasperi]

Yeah I don't think its a valid use case. Just something to be aware of that the title will be shown until the image is loaded then if the download is done asynchronously.

[kkafar]

I've refactored the code a bit. I'll be willing to land this if you confirm that also works for you.

[johankasperi]

I've refactored the code a bit. I'll be willing to land this if you confirm that also works for you.

Thank you! And thanks for explaining how RCTImageLoader works in production/debug mode. Your refactor is working in my testing so feel free to merge

[johankasperi]

I've refactored the code a bit. I'll be willing to land this if you confirm that also works for you.

Thank you! And thanks for explaining how RCTImageLoader works in production/debug mode. Your refactor is working in my testing so feel free to merge

One thing to be aware of now though is that you cant load images of type ImageURISource in debug mode. It works in production mode. But using ImageURISource for icons in the header should not be a common use case

[johankasperi]

@kkafar I refactored now so we got the changes from #3347 Feel free to have a look at it. Thanks!

[kkafar]

Thanks for catching this.

I'll land this PR once CI passes.

Regarding ImageURISource - thanks for reporting this. We might wanna handle this separately.