feat(iOS 26, Stack v4): support for new search bar placements, integration with toolbar

[kligarski]

Description

This PR addresses changes to search bar on iOS 26.

Closes https://github.com/software-mansion/react-native-screens-labs/issues/339.

After merging, docs in react-navigation should also be updated, issue for this: https://github.com/software-mansion/react-native-screens-labs/issues/384.

Changes

• add support for new search bar placements (integrated, integratedButton, integratedCentered),
• add prop for controlling new search bar toolbar integration on iPhone (allowToolbarIntegration),
• deprecate one of the placements (inline has been renamed to integrated starting from iOS 26) and cancelButtonText (search cancel button does not have any text on iOS 26),
• reduce scope of workaround introduced in fix(iOS, Stack v4): fix missing search bar on root screen on iOS 26 #3098 (only to stacked placement)
• disable recycling for SearchBar (workaround above does not solve all bugs with search bar on iOS 26).

Screenshots / GIFs

Simulator.Screen.Recording.-.iPhone.16.Pro.-.2025-08-28.at.12.17.00.mov

Note

If you use integrated, integratedButton or integratedCentered, the integration into toolbar is delayed and causes a flash (you can see it on the video). This bug happens also in bare UIKit app. The best workarounds I could find are:

• use automatic with transparent header,
• use automatic with hideWhenScrolling: true

Details: https://github.com/software-mansion/react-native-screens-labs/issues/331#issuecomment-3232909939

There is also another bug (also reproducible but due to how tabs+freeze work in screens, it's a little bit worse in our case). I think it's more of an edge case though (if you use tab with search systemItem but disable toolbar integration, the search bar is empty). Details: https://github.com/software-mansion/react-native-screens-labs/issues/331#issuecomment-3233232295

Test code and steps to reproduce

Run Test3168. You can also see other Search Bar related test screens like SearchBar.tsx, Test758, Test1097.

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

[kmichalikk]

Looks good overall.
There are glitches with some combinations, but there are present in native apps, too.
I'm worried that we didn't check out enough combinations, though. We should also see what happens when we set different styling options for header.
When I disabled headerTransparent, it broke 'automatic' too:

automatic-header-transparent-false.mov

[kligarski]

When I disabled headerTransparent, it broke 'automatic' too:

I managed to reproduce this as well in bare UIKit app. By default, UIKit uses hideWhenScrolling: true but we use hideWhenScrolling: false, that's why it was hard to reproduce. I described the details in PR description and corresponding issue.

[kkafar]

Few adjustments request & we're good.

[kkafar]

Looking good, thank you!