feat(iOS): support UIBarButtonItem in header #2987

johankasperi · 2025-06-27T15:55:18Z

Description

The current implementation of headerLeft and headerRight adds a react view as a custom view in a UIBarButtonItem. This implementation is sufficient at most times but I believe we can achieve greater "native feel" if the native stack has an protocol for adding actual UIBarButtonItems in the header. As the UIBarButtonItems has properties and features that can be difficult to mimic with a react view.

Also with the introduction of iOS 26, using only custom views in UIBarButtonItem presents some limitations. Mainly that the adaptive tint color (based on the underlying view) is not working on a UIBarButtonItem with a custom view as demonstrated below under "Screenshots".

Changes

This PR adds the properties headerRightItems and headerLeftItems on the native stack Screen that makes it possible to add one or several UIBarButtonItem to the right/left of the header and/or functions returning a React Node. Most of the features of the UIBarButtonItem is supported (see either "Bar Button Items" in the example apps or the type definition).

Screenshots / GIFs

Non adaptive tint color when using old property `headerRight` on iOS 26

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2025-06-27.at.16.31.10.mov

Adaptive tint color when using new property `headerRightBarButtonItems` on iOS 26

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2025-06-27.at.16.28.30.mov

UIBarButtonItem with style "prominent" on iOS 26

UIBarButtonItem with UIMenu on iOS 26

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2025-06-27.at.16.29.02.mov

Test code and steps to reproduce

I've created a screen named "Bar Button Items" in the example app that showcases all of the proposed features.

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
  Unsure if I need to do this. I'm targeting react-navigation v6 and above so no JS changes has been made to react-native-screens in this PR. Would appreciate some guidance to if and where I should make documentation changes if needed. Thank you!
Ensured that CI passes

johankasperi · 2025-06-27T16:07:24Z

Related PR in react-navigation: react-navigation/react-navigation#12657

Pnlvfx · 2025-07-02T22:38:43Z

i like this

kkafar · 2025-07-18T13:08:36Z

Hey! This is really promising. We're working currently on support for iOS 26 etc. and we're doing general overhaul of the lib. As of now, we're not sure what will be the API shape & scope, therefore I won't review it for now. Once we settle the internal discussion I'll revisit your implementation. I'm sure we'll be able to land it in some form.

johankasperi · 2025-08-04T12:50:59Z

Hey! This is really promising. We're working currently on support for iOS 26 etc. and we're doing general overhaul of the lib. As of now, we're not sure what will be the API shape & scope, therefore I won't review it for now. Once we settle the internal discussion I'll revisit your implementation. I'm sure we'll be able to land it in some form.

I'm really glad you liked it! Yeah I saw that you have done a bunch of iOS 26 related PRs and changes to the API so I understand that my suggestion may not match the shape you are targeting. Please let me know if there are any changes I can do right now and I will happily do them asap. I truly believe something like this would be awesome for react-native-screens when iOS 26 is out of beta.

kmichalikk

Hi
Great stuff. We're looking at your PR and would like to merge the changes soon. Here are some comments from me, and I believe @kkafar wants to look more closely in the following days.

Also, please update the PR with changes from main branch. There could be some conflicts.

apps/src/screens/BarButtonItems.tsx

ios/RNSBarButtonItem.h

ios/RNSBarButtonItem.mm

apps/src/screens/BarButtonItems.tsx

johankasperi · 2025-08-06T12:08:32Z

Hi Great stuff. We're looking at your PR and would like to merge the changes soon. Here are some comments from me, and I believe @kkafar wants to look more closely in the following days.

Also, please update the PR with changes from main branch. There could be some conflicts.

Thank you! I've updated the PR with changes from main and resolved all conflicts

## Description From discussion in #2987 (comment). We should rename the class into something more specific because it really does one specific thing. ## Changes title ## Test code and steps to reproduce No changes, disabling back button menu should still work. You can modify BottomTabsTest / Tab4 with `screenOption={{ headerBackButtonMenuEnabled: false }}`

kkafar · 2025-08-12T15:50:38Z

Hey, I most likely won't find time tomorrow & I'm going for a two week PTO on Thursday. I'll try to review this as one of first things after I'm back from PTO.

:sorry:

johankasperi · 2025-08-12T20:40:19Z

Hey, I most likely won't find time tomorrow & I'm going for a two week PTO on Thursday. I'll try to review this as one of first things after I'm back from PTO.

:sorry:

Hey! No worries! Have a nice PTO 😊

johankasperi · 2025-08-18T21:44:40Z

@kmichalikk I added support for systemImage (using SF Symbols) in this commit 8981d6a Feel free to take a look or try it out whenever you have the chance. Thanks!

johankasperi · 2025-08-19T21:41:16Z

@kmichalikk refactored everything a bit in af27795

I realised that users might want to combine native UIBarButtonItems and React Nodes in the header left and right. So renamed headerRightBarButtonItems and headerLeftRightBarButtonItems to headerRightItems and headerLeftItems. These two properties now accepts an array containing either dicts for UIBarButtonItems or functions returning a React Node. The new functionality is shown in the screen "ReactNodeButtonDemo".

kmichalikk

I wasn't able to properly run this probably because of some issues with linking to react-navigation PR - buttons were not displayed at all. I'll try again later. In the meantime I have two small nitpicks.

ios/RNSBarButtonItem.mm

apps/src/screens/BarButtonItems.tsx

johankasperi · 2025-08-21T11:02:06Z

I wasn't able to properly run this probably because of some issues with linking to react-navigation PR - buttons were not displayed at all. I'll try again later. In the meantime I have two small nitpicks.

My bad! I forgot to push my latest commits to react-navigation. Should be working now

johankasperi · 2025-09-02T10:06:47Z

@kmichalikk I added support for hidesSharedBackground: boolean when rendering custom React Elements. Making it possible to show them without the liquid glass effect (see screenshot below). Feel free to have a look and try it out!

Simulator Screenshot - iPhone 16 Pro - 2025-09-02 at 12 05 26

kmichalikk

Looks good 👍
Some nitpick & suggestions below.
I pulled the PR locally and merged main, works fine but found some visual bugs that I suspect are native, but haven't checked that yet.

ios/RNSBarButtonItem.mm

kmichalikk · 2025-09-03T07:26:29Z

ios/RNSBarButtonItem.mm

+#if defined(__IPHONE_OS_VERSION_MAX_ALLOWED) && defined(__IPHONE_26_0) && \
+    __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_26_0
+        if (@available(iOS 26.0, *)) {
+          self.style = UIBarButtonItemStyleProminent;
+        }
+#endif


For iOS < 26 there is no style set explicitly here; maybe, to be consistent, we should set it to something? And please mention the difference for iOS versions somewhere in the docs.

I don't think we need to set it to something else on iOS < 26. I believe it's better to leave it untouched and use the default style of the OS when the prominent style is not available. UIBarButtonItemStylePlain is the default style of iOS < 26.

And about docs, I'm linking to the Apple docs in the JSDoc comments in the type declaration. I'm also mentioning that "Prominent" is only available on iOS 26. https://github.com/johankasperi/react-navigation/blob/668b77545440c51f473bf7e392a6b8b946eec8f9/packages/native-stack/src/types.tsx#L729

Could you point me to where in the docs I should also mention this?

One could also argue that linking to the iOS docs is sufficient, especially during the beta period when stuff might be changed by Apple, since by trying to copy Apples docs to the React Native Screen docs the RNS docs might become dated quickly when Apple are doing changes. But I'm not gonna be the judge of that 😊

kmichalikk · 2025-09-03T07:58:04Z

apps/src/screens/BarButtonItems.tsx

@@ -0,0 +1,412 @@
+// NOTE: The full native feature set (style, image, menu, etc.) is available, but the TS types in src/types.tsx need to be updated to match. This example uses only the currently typed props (title, icon, onPress, enabled).


In this case we should add some documentation to src/types.tsx, maybe also to GUIDE_FOR_LIBRARY_AUTHORS, especially the different cases when the behavior is different for iOS 26 vs 18. I saw there is more documentation in the PR for react-navigation, but it would be nice to have it also here in screens.

Do you mean this interface?

react-native-screens/src/types.tsx

Line 545 in 5abbab3

export interface ScreenStackHeaderConfigProps extends ViewProps {

And in GUIDE_FOR_LIBRARY_AUTHORS, do you mean I should add it under this section? https://github.com/software-mansion/react-native-screens/blob/main/guides/GUIDE_FOR_LIBRARY_AUTHORS.md#screenstackheaderconfig

That's what I was thinking about, It'd be good to have something in the same place where other screens components' props are defined for quick reference when someone new jumps in. IN GUIDE... there is this section "Below is a list of properties that can be set with ScreenStackHeaderConfig component:" and since you are adding new props, we should keep it in sync & write something there. Same for src/types.tsx.

Thansk for pointing me to where I should write something. I will do that asap

Added the types in this commit 3e2f63d

Added docs in this commit b41acf8

apps/src/screens/BarButtonItems.tsx

ios/RNSScreenStackHeaderConfig.mm

apps/src/screens/BarButtonItems.tsx

joluet · 2025-09-05T11:07:05Z

I tested this and it seems to fix several UI issues on iOS 26. Thank you @johankasperi ! 🙏

@kkafar @kmichalikk is there any chance this might be released in the next few days? 😇
We need this to get our app ready for iOS 26 with a deadline in mid September. 🙈

johankasperi · 2025-09-05T11:18:58Z

I tested this and it seems to fix several UI issues on iOS 26. Thank you @johankasperi ! 🙏

@kkafar @kmichalikk is there any chance this might be released in the next few days? 😇 We need this to get our app ready for iOS 26 with a deadline in mid September. 🙈

Thank you! Don't know your circumstances for the deadline but wanted to share that you can opt out from the new design with UIDesignRequiresCompatibility in your Info.plist

joluet · 2025-09-05T11:22:45Z

Thank you! Don't know your circumstances for the deadline but wanted to share that you can opt out from the new design with UIDesignRequiresCompatibility in your Info.plist

Apple is considering our App for featuring. So, opting out is no an option for us. :/

johankasperi · 2025-09-05T11:27:31Z

Thank you! Don't know your circumstances for the deadline but wanted to share that you can opt out from the new design with UIDesignRequiresCompatibility in your Info.plist

Apple is considering our App for featuring. So, opting out is no an option for us. :/

I understand. Congrats for being considered for featuring!

kmichalikk

Again, great job. I left a comment about the docs, nothing else from me.

kkafar · 2025-09-08T14:20:43Z

I wanna update you, that I'm starting to look at this PR 😅 I can't say however we'll be able to land in in just couple of days, since it's a bit chunky.

Remember that you always have patch-package at your disposal (know that it is kinda clunky solution, but if forced to - may be a way to go).

johankasperi force-pushed the ios-bar-button-item branch from 4e8a7b3 to a86dbb3 Compare June 27, 2025 15:59

johankasperi mentioned this pull request Jun 27, 2025

feat(ios): support UIBarButtonItem in header react-navigation/react-navigation#12657

Open

kmichalikk reviewed Aug 5, 2025

View reviewed changes

apps/src/screens/BarButtonItems.tsx Outdated Show resolved Hide resolved

ios/RNSBarButtonItem.h Show resolved Hide resolved

ios/RNSBarButtonItem.mm Outdated Show resolved Hide resolved

apps/src/screens/BarButtonItems.tsx Outdated Show resolved Hide resolved

johankasperi force-pushed the ios-bar-button-item branch 2 times, most recently from e9b25c0 to f53da7d Compare August 6, 2025 10:00

kmichalikk requested a review from kkafar August 7, 2025 04:56

johankasperi force-pushed the ios-bar-button-item branch from 1a6bce3 to 2750468 Compare August 7, 2025 16:44

This was referenced Aug 11, 2025

[iOS] Header buttons are not centered in iOS 26 (w/ some investigation done on my end) #2990

Open

chore(iOS): Rename RNSUIBarButtonItem to RNSBackBarButtonItem #3119

Merged

johankasperi force-pushed the ios-bar-button-item branch from ac9e6bd to bbcb13c Compare August 12, 2025 20:38

johankasperi force-pushed the ios-bar-button-item branch from e2ae763 to 1bf07e5 Compare August 14, 2025 20:12

johankasperi requested a review from kmichalikk August 18, 2025 21:44

kmichalikk reviewed Aug 20, 2025

View reviewed changes

ios/RNSBarButtonItem.mm Outdated Show resolved Hide resolved

apps/src/screens/BarButtonItems.tsx Outdated Show resolved Hide resolved

johankasperi force-pushed the ios-bar-button-item branch from 4c250ef to 683264d Compare August 25, 2025 12:28

johankasperi force-pushed the ios-bar-button-item branch from 683264d to 562e893 Compare September 2, 2025 07:31

kmichalikk reviewed Sep 3, 2025

View reviewed changes

johankasperi force-pushed the ios-bar-button-item branch from 9cd5ae8 to 6cda9e9 Compare September 4, 2025 12:23

basic stuff working but needs cleanup

c0bd093

johankasperi added 12 commits September 4, 2025 23:00

submodule changes

21e9425

remove ios14 check

b3129c4

rename systemImage to sfSymbolName

05e2b65

react-navigation submodule change

a0520be

submodule update again

735a364

submodule changes

b7128d9

submodule changes

8e6ce32

add hidesSharedBackground prop to custom view bar button items

08b8a05

fix small nit

7e49061

extract setting titlestyle to method

b83fe1f

use RNS_IPHONE_OS_VERSION_AVAILABLE

b936158

add support for sfSymbolName in submenu

49fb1b8

johankasperi force-pushed the ios-bar-button-item branch from 03ed736 to 49fb1b8 Compare September 4, 2025 21:03

johankasperi added 4 commits September 4, 2025 23:12

refactor badge code into method

5db877b

refactor create UIMenu into a create UIAction method

3a23e44

tsc example

bcf6e06

remove usage of index

480a975

johankasperi requested a review from kmichalikk September 5, 2025 06:50

kmichalikk reviewed Sep 5, 2025

View reviewed changes

johankasperi added 3 commits September 7, 2025 22:40

add types to ScreenStackHeaderConfigProps

3e2f63d

correct type name

c799267

add docs

b41acf8

johankasperi requested a review from kmichalikk September 7, 2025 20:57

add some missing docs

4a622a9

kkafar mentioned this pull request Sep 8, 2025

Add support for iOS 26 subtitle in native stack #3200

Open

8 tasks

		@@ -0,0 +1,412 @@
		// NOTE: The full native feature set (style, image, menu, etc.) is available, but the TS types in src/types.tsx need to be updated to match. This example uses only the currently typed props (title, icon, onPress, enabled).

Uh oh!

feat(iOS): support UIBarButtonItem in header #2987

Are you sure you want to change the base?

feat(iOS): support UIBarButtonItem in header #2987

Conversation

johankasperi commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Screenshots / GIFs

Non adaptive tint color when using old property headerRight on iOS 26

Adaptive tint color when using new property headerRightBarButtonItems on iOS 26

UIBarButtonItem with style "prominent" on iOS 26

UIBarButtonItem with UIMenu on iOS 26

Test code and steps to reproduce

Checklist

Uh oh!

johankasperi commented Jun 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Pnlvfx commented Jul 2, 2025

Uh oh!

kkafar commented Jul 18, 2025

Uh oh!

johankasperi commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kmichalikk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

johankasperi commented Aug 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkafar commented Aug 12, 2025

Uh oh!

johankasperi commented Aug 12, 2025

Uh oh!

johankasperi commented Aug 18, 2025

Uh oh!

johankasperi commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kmichalikk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

johankasperi commented Aug 21, 2025

Uh oh!

johankasperi commented Sep 2, 2025

Uh oh!

kmichalikk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johankasperi Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

johankasperi commented Jun 27, 2025 •

edited

Loading

Non adaptive tint color when using old property `headerRight` on iOS 26

Adaptive tint color when using new property `headerRightBarButtonItems` on iOS 26

johankasperi commented Jun 27, 2025 •

edited

Loading

johankasperi commented Aug 4, 2025 •

edited

Loading

johankasperi commented Aug 6, 2025 •

edited

Loading

johankasperi commented Aug 19, 2025 •

edited

Loading

johankasperi Sep 4, 2025 •

edited

Loading