feat(iOS, Tabs): add bottomAccessory support #3288

kligarski · 2025-10-07T12:01:11Z

Description

Adds support for botttomAccessory in Bottom Tabs starting from iOS 26.

Synchronization with ShadowTree

When bottom accessory transitions between regular and inline environments (when tab bar is minimized), we need to update the position and size of the bottom accessory. Our approach is different for RN < 0.82 and RN >= 0.82.

Legacy architecture & New architecture prior to `[email protected]`

In versions prior to RN 0.82, we need use DisplayLink and presentation layer frames to get intermediate frames during the transition. This approach however has a major drawback - we are always at least one frame behind the current state as we're observing what is currently presented. When the difference in size/origin between frames is significant, you can see the content "jumping". In the case of bottom accessory, this is especially visible when using non-translucent background and transitioning from inline to regular environment (pay attention to the right edge of the accessory).

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.08.31.39.mov

Introduction of synchronous state updates in RN 0.82 (more details below) does not improve the situation when using this approach as we are still going to be at least one frame behind the animation.

`[email protected]` and higher

Thanks to introduction of synchronous state updates in RN 0.82, we can rely fully on native mechanisms for handling the transition. Bottom accessory only receives the final frame of the transition and thanks to synchronous state updates, we can immediately recalculate the layout in the Shadow Tree and update the Host Tree. This allows Core Animation framework to make the transition smooth. Details of how we think this works are available here.

Unfortunately, when using react-native, the situation is a little bit more complicated.

Text

Text component behaves differently to the native platform. During the transition, it immediately adapts to the final frame size and then it is stretched. In bare UIKit app, the text adapt to new frame size at the end of the transition.

`react-native`	`UIKit`
Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.10.16.33.mov	Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.10.22.22.mov

This requires more investigation and potentially changes in react-native.

Borders

CoreAnimation does not support non-uniform borders so react-native handles them in a custom way that does not seem to be compatible with the transition mechanism.

non-uniform borders	uniform borders + CA enabled
Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.10.28.39.mov	Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.10.32.17.mov

This requires more investigation and potentially changes in react-native.

Images

Similar problem (in a way it looks, not the exact mechanism of the bug) happens when using images e.g. with width: 100%.

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.11.08.09.mov

This requires more investigation and potentially changes in react-native.

Mounting/unmounting views during transition

While state updates are performed synchronously, any changes to React Element Tree in reaction to environment change are handled asynchronously. We think that this is why the transition handled by CoreAnimation breaks when trying to mount/unmount components on environment change.

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.08.16.12.mov

Here, we try to remove the note icon. Unfortunately, the rest of the layout does not adapt. You can also observe the text stretching as mentioned 2 sections above.

Changes

add BottomTabsAccessory JS component and use it in BottomTabs,
add BottomTabsAccessoryComponentView, BottomTabsAccessoryEventEmitter, BottomTabsAccessoryComponentViewManager,
add BottomAccessoryHelper to synchronize state between Host and ShadowTree,
adapt BottomTabsHost to accept 2 types of children (Screen and Accessory),
add test screen.

Test code and steps to reproduce

Run Test3288.

Checklist

Included code example that can be used to test this change
Updated TS types
Updated documentation:
Ensured that CI passes

t0maboro

I haven't finished yet, flushing the 1st part

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryComponentDescriptor.h

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryShadowNode.cpp

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryState.h

ios/bottom-tabs/accessory/RNSBottomTabsAccessoryComponentView.mm

ios/bottom-tabs/RNSBottomTabsAccessoryComponentView.h

ios/bottom-tabs/RNSBottomTabsAccessoryComponentView.mm

ios/bottom-tabs/accessory/RNSBottomTabsAccessoryComponentView.mm

aledebla03 · 2025-10-20T09:48:55Z

Is there any ETA? Looks fantastic 🔥

kligarski · 2025-10-20T12:32:40Z

I'm glad you like it. Recently I had to switch my focus to investigate some higher priority issues related to iOS 26 support. Once I finish, I'll come back to bottom accessory.

kkafar

Thank you for very nice PR description. It's really helpful during review process. Keep it up!

Here I address the problems mentioned in PR description. I'll do a follow-up review regarding the code.

The "text" behaviour you describe is fine. Having it at the beginning / end is not that much of a difference. Text animations are expensive, probably one of the reasons this is done this way in UIKit + the accessory view *does not seem like a place for pages of text.

The "borders problem" is the same we have with sync updates in split view. @t0maboro already created ticket for this. We should start conversation with react-native team how we should approach this problem.

The "images" problem is interesting. It would be worth to investigate it a bit, initially in direction: who is responsible for image frame change. Is that Yoga or platform framework? Who interpolates it?

The "Mounting/unmounting views during transition" problem

Yeah, it looks ugly. But it should not be like that. At least since 0.82. There are mechanisms in RN to emit sync events to JS now. Take a look here for usage examples. We should try that out. We can schedule a call here. Using this we should be able to trigger sync react render & have it hopefully nicely animated.

kkafar

This PR looks really good overall. Great job. Few comments here and there.

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryComponentDescriptor.h

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryShadowNode.cpp

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryState.h

ios/bottom-tabs/RNSBottomTabsAccessoryEventEmitter.h

ios/bottom-tabs/host/RNSBottomTabsHostComponentView.mm

ios/bottom-tabs/RNSBottomTabsHostComponentView.mm

ios/bottom-tabs/RNSTabBarController.mm

src/components/bottom-tabs/BottomTabs.types.ts

kkafar · 2025-11-05T08:33:29Z

Bottom accessory view + view mount / unmount during transition between environments.

patched "sync" events	"sync" events (current state)
bottom-accessory-with-sync-events.mov	Simulator.Screen.Recording.-.iPhone.17.Pro.-.2025-10-13.at.08.16.12.mov

kkafar

Really good job. The PR is in really good shape & code is of high quality - kudos.

I've got few remarks, refactor requests & questions. Please answer them.

kkafar · 2025-11-06T11:33:07Z

common/cpp/react/renderer/components/rnscreens/RNSBottomTabsAccessoryComponentDescriptor.h

+        shadowNode.getState());
+    auto stateData = state->getData();
+
+    if (stateData.frameSize.width != 0 && stateData.frameSize.height != 0) {


We need refactor across whole codebase that will extract this particular condition to a separate function. We have too many places where this is stated explicitly & it is hard to change definition of what "empty state" means. Let's create ticket for this, please.

kkafar · 2025-11-06T12:07:58Z

ios/bottom-tabs/accessory/RNSBottomAccessoryHelper.mm

+namespace react = facebook::react;
+
+@implementation RNSBottomAccessoryHelper {
+  RNSBottomTabsAccessoryComponentView *_bottomAccessoryView;


Will this create retain cycle? If so, let's document it here & state how to break it.

kkafar · 2025-11-06T12:38:07Z

ios/bottom-tabs/accessory/RNSBottomAccessoryHelper.mm

+                    UITabAccessoryEnvironment environment =
+                        self->_bottomAccessoryView.traitCollection.tabAccessoryEnvironment;
+                    [self->_bottomAccessoryView.reactEventEmitter emitOnEnvironmentChangeIfNeeded:environment];


Do you recall whether this callback is invoked only when the trait has really changed value? Or is it called also if some one just wrote to the value? My question basically is whether we should diff with previousTraitCollection inside the handler or is this done for us?

kkafar · 2025-11-06T12:41:19Z

ios/bottom-tabs/accessory/RNSBottomAccessoryHelper.mm

+  return _bottomAccessoryView.superview.superview;
+}
+
+- (void)notifyFrameUpdate


I'd like the naming of this method to be more specific. Something like nativeWrapperViewChangedFrame or something of this kind.

kkafar · 2025-11-06T12:42:35Z

ios/bottom-tabs/accessory/RNSBottomAccessoryHelper.mm

+  // We want the enable the display link as well so that it takes over later with correct origin.
+  if (!_initialStateUpdateSent) {
+    CGRect frame = CGRectMake(0, 0, self.nativeWrapperView.frame.size.width, self.nativeWrapperView.frame.size.height);
+    [self updateShadowStateWithFrame:frame];


Let's go with SplitView example & create a shadow state proxy for handling all shadow state updates.

Also the proxy should be retained by the view & helper should access it via the view.

kkafar · 2025-11-06T14:30:11Z

ios/bottom-tabs/host/RNSBottomTabsHostComponentView.mm

-  [_reactSubviews insertObject:childScreen atIndex:index];
+  [super insertReactSubview:subview atIndex:index];
+  [self validateAndHandleReactSubview:subview didMount:YES];
+  [_reactSubviews insertObject:subview atIndex:index];


Also why isn't this call to insert / remove object from _reactSubview handled inside the callback?

kkafar · 2025-11-06T14:31:08Z

ios/bottom-tabs/host/RNSBottomTabsHostComponentView.mm


+#pragma mark - Common
+
+- (void)validateAndHandleReactSubview:(UIView *)subview didMount:(BOOL)mount


Suggested change

- (void)validateAndHandleReactSubview:(UIView *)subview didMount:(BOOL)mount

- (void)validateAndHandleReactSubview:(UIView *)subview shouldMount:(BOOL)mount

kkafar · 2025-11-06T14:33:42Z

src/components/bottom-tabs/BottomTabs.tsx

+            <BottomTabsAccessoryContent environment="regular">
+              {bottomAccessory('regular')}
+            </BottomTabsAccessoryContent>
+            <BottomTabsAccessoryContent environment="inline">


Do we do this double-rendering trick only on >= 82? whaat

kkafar · 2025-11-06T14:36:59Z

src/components/bottom-tabs/BottomTabsAccessory.tsx

+    <BottomTabsAccessoryNativeComponent
+      {...props}
+      collapsable={false}
+      style={[props.style, styles.container]}


Suggested change

style={[props.style, styles.container]}

style={[props.style, styles.absolutePositioned]}

or positionAbsolute or align with predefined style sets from StyleSheet.xxx namespace.

kkafar · 2025-11-06T14:42:24Z

src/components/bottom-tabs/BottomTabsAccessoryContent.tsx

+    width: '100%',
+    height: '100%',


Is this intentionally chosen over right: 0, bottom: 0?

kligarski added 18 commits September 30, 2025 16:34

add skeleton

d8eaeae

WIP

226954c

controlers

28ac025

helper and wrapper, invalidating display link

a71d92b

refactor

6a9c2a1

refactor 2

5ea44e8

invalidating skeleton

775ae70

don't update if tab controllers did not change

a4a84e6

use correct type in RCTInvalidating's invalidate

7e608c4

add environment change events

4df66d2

ios 26 availability, typo

1f8b2da

refactor JS API

35aae34

use KVO for native bottom accessory view's frame

537adad

Paper implementation

7eb5f64

add test screen

bea9501

revert changes to TestBottomTabs

9bead07

remove custom wrapper

33bfde5

fix inserting and removing react subviews in host component

4ba4a5c

Ubax mentioned this pull request Oct 10, 2025

[sdk-55][expo-router] add support for bottom tab accessory in native tabs expo/expo#39114

Closed

3 tasks

kligarski added 6 commits October 13, 2025 07:54

restore App.tsx

cac1c98

Merge branch 'main' into @kligarski/bottom-accessory

bdaada7

in-code docs refinement

aadf116

add iOS version guards

1c34da9

fix guards

31c3bef

fix build on Paper

a58c723

kligarski marked this pull request as ready for review October 13, 2025 09:10

kligarski requested review from kkafar, kmichalikk and t0maboro October 13, 2025 09:11

t0maboro reviewed Oct 13, 2025

View reviewed changes

kkafar reviewed Oct 24, 2025

View reviewed changes

kligarski added 13 commits November 3, 2025 12:50

Merge branch 'main' into @kligarski/bottom-accessory

6b213bd

adapt test screen to new icons API

28ee322

suggestions from code review part 1

44f4c5f

fix renamed prop for Paper

5ca50ed

extract UITabAccessoryEnvironment conversion

2c69f3e

remove duplication in mounting/unmounting code

1696be4

remove redundant flex

5f83151

use self-closing tag

2f5d7c3

unify naming for content offset

e98390a

use ifNeeded suffix

946b546

import type JS

cdb7d84

refactor handling subview change in bottom tabs host

65524d8

add missing guards

59cee3a

t0maboro approved these changes Nov 4, 2025

View reviewed changes

kligarski mentioned this pull request Nov 5, 2025

feat(iOS, Tabs): Migrate to new invalidate method #3367

Draft

2 tasks

kligarski added 6 commits November 5, 2025 12:09

Merge branch 'main' into @kligarski/bottom-accessory

99e2a54

view swap approach PoC

397d175

cleanup

e19e143

maybe fix build

9e2a8f8

cleanup

0b3af56

update docs

b9d1bca

kligarski requested review from kkafar and t0maboro November 6, 2025 08:06

ifdef RCT_NEW_ARCH_ENABLED -> if RCT_NEW_ARCH_ENABLED

7ab2cb4

kkafar reviewed Nov 6, 2025

View reviewed changes


		#pragma mark - Common

		- (void)validateAndHandleReactSubview:(UIView *)subview didMount:(BOOL)mount

	style={[props.style, styles.container]}
	style={[props.style, styles.absolutePositioned]}

Uh oh!

feat(iOS, Tabs): add bottomAccessory support #3288

Are you sure you want to change the base?

feat(iOS, Tabs): add bottomAccessory support #3288

Conversation

kligarski commented Oct 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Synchronization with ShadowTree

Legacy architecture & New architecture prior to [email protected]

[email protected] and higher

Text

Borders

Images

Mounting/unmounting views during transition

Changes

Test code and steps to reproduce

Checklist

Uh oh!

t0maboro left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

aledebla03 commented Oct 20, 2025

Uh oh!

kligarski commented Oct 20, 2025

Uh oh!

kkafar left a comment • 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!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kkafar commented Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kkafar left a comment • 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!

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!

kligarski commented Oct 7, 2025 •

edited

Loading

Legacy architecture & New architecture prior to `[email protected]`

`[email protected]` and higher

kkafar left a comment •

edited

Loading

kkafar commented Nov 5, 2025 •

edited

Loading

kkafar left a comment •

edited

Loading