feat(ios): add backgroundColor prop to top bar buttons

Add a new `backgroundColor` option to `OptionsTopBarButton` that sets a
solid color on the iOS 26 Liquid Glass circular platter behind React
component bar buttons.

Native implementation:
- Parse `backgroundColor` in RNNButtonOptions (init/copy/merge)
- Pass the resolved UIColor from RNNButtonBuilder to
  RNNReactButtonView.buttonBackgroundColor
- syncButtonBackground targets the _UINavigationBarPlatter-
  SubviewContainerView (self.superview³) and applies the color,
  cornerRadius, and clipsToBounds to keep it circular
- Called from both didMoveToWindow (early, prevents flash on push) and
  layoutSubviews (handles re-layouts)
- When buttonBackgroundColor is nil the platter resets to clearColor,
  preventing color leaking between buttons during navigation transitions

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: IsaacIsrael

ios/RNNButtonBuilder.mm

@@ -30,6 +30,7 @@ - (RNNUIBarButtonItem *)build:(RNNButtonOptions *)button
                                          parentComponentId:parentComponentId
                                              componentType:RNNComponentTypeTopBarButton
                                        reactViewReadyBlock:nil];
+        view.buttonBackgroundColor = [button.backgroundColor withDefault:nil];
         return [[RNNUIBarButtonItem alloc] initWithCustomView:view
                                                 buttonOptions:button
                                                       onPress:onPress];

ios/RNNButtonOptions.h

@@ -24,6 +24,7 @@
 @property(nonatomic, strong) RNNIconBackgroundOptions *iconBackground;
 @property(nonatomic, strong) Bool *disableIconTint;
 @property(nonatomic, strong) Bool *hideSharedBackground;
+@property(nonatomic, strong) Color *backgroundColor;
 
 - (RNNButtonOptions *)withDefault:(RNNButtonOptions *)defaultOptions;
 

ios/RNNButtonOptions.mm

@@ -26,6 +26,7 @@ - (instancetype)initWithDict:(NSDictionary *)dict {
     self.systemItem = [TextParser parse:dict key:@"systemItem"];
     self.disableIconTint = [BoolParser parse:dict key:@"disableIconTint"];
     self.hideSharedBackground = [BoolParser parse:dict key:@"hideSharedBackground"];
+    self.backgroundColor = [ColorParser parse:dict key:@"backgroundColor"];
 
     return self;
 }
@@ -51,6 +52,7 @@ - (RNNButtonOptions *)copy {
     newOptions.systemItem = self.systemItem.copy;
     newOptions.disableIconTint = self.disableIconTint.copy;
     newOptions.hideSharedBackground = self.hideSharedBackground.copy;
+    newOptions.backgroundColor = self.backgroundColor.copy;
     return newOptions;
 }
 
@@ -92,6 +94,8 @@ - (void)mergeOptions:(RNNButtonOptions *)options {
         self.disableIconTint = options.disableIconTint;
     if (options.hideSharedBackground.hasValue)
         self.hideSharedBackground = options.hideSharedBackground;
+    if (options.backgroundColor.hasValue)
+        self.backgroundColor = options.backgroundColor;
 }
 
 - (BOOL)shouldCreateCustomView {

ios/RNNReactButtonView.h

@@ -6,4 +6,6 @@
 
 @interface RNNReactButtonView : RNNComponentView
 
+@property(nonatomic, strong) UIColor *buttonBackgroundColor;
+
 @end

ios/RNNReactButtonView.mm

@@ -43,6 +43,13 @@ - (void)updateConstraintsToFitSize {
     }
 }
 
+- (void)didMoveToWindow {
+    [super didMoveToWindow];
+    if (self.window) {
+        [self syncButtonBackground];
+    }
+}
+
 - (void)layoutSubviews {
     [super layoutSubviews];
     if (!_didCenter && self.superview && self.frame.size.width > 0) {
@@ -54,6 +61,16 @@ - (void)layoutSubviews {
             self.layer.affineTransform = CGAffineTransformMakeTranslation(tx, 0);
         }
     }
+    [self syncButtonBackground];
+}
+
+- (void)syncButtonBackground {
+    UIView *target = self.superview.superview.superview;
+    if (!target || target.bounds.size.height <= 0) return;
+
+    target.backgroundColor = _buttonBackgroundColor ?: [UIColor clearColor];
+    target.layer.cornerRadius = target.bounds.size.height / 2.0;
+    target.clipsToBounds = YES;
 }
 
 - (NSString *)componentType {

src/interfaces/Options.ts

@@ -658,6 +658,12 @@ export interface OptionsTopBarButton {
    * @see {@link https://developer.android.com/guide/topics/resources/menu-resource|Android developer guide: Menu resource}
    */
   showAsAction?: 'ifRoom' | 'withText' | 'always' | 'never';
+  /**
+   * (iOS 26+ only) Set a solid background color on the circular Liquid Glass
+   * platter behind the button. When nil the platter is reset to clear.
+   * #### (iOS specific)
+   */
+  backgroundColor?: Color;
 }
 
 export interface OptionsSearchBar {