Ios26 Navigation

iOS 26 Navigation in RNN

When this applies

Use this skill any time work touches:

• Top bar / navigation bar appearance, buttons, titles, or search
• Bottom tab bar appearance, items, badges, or layout
• Toolbar items or bar button styling
• Any @available(iOS 26.0, *) branch
• iOS 26-only bugs (Liquid Glass clipping, tab bar floating, button platter, scroll-edge effects)

Pair this with rnn-codebase (repo navigation) and rnn-e2e-runner (validation).

Build configuration

• Always Release for verification — see workspace rule rnn-build-release.mdc. Debug masks iOS 26 layout/transition issues.
• Xcode 26.1 toolchain: DEVELOPER_DIR=/Applications/Xcode_26.1.app/Contents/Developer
• Simulator: iPhone 17 Pro Max (iOS 26 default)
• Do not disable Fabric / New Architecture (user rule).
• Compatibility opt-out flag: UIDesignRequiresCompatibility in Info.plist. RNN reads it in RNNReactButtonView.designRequiresCompatibility to fall back to pre-iOS-26 layout. Always honor it in new iOS 26 code paths.

Apple iOS 26 API map

1. Liquid Glass material

The system bar material on UINavigationBar, UITabBar, UIToolbar is always translucent / glass by default. configureWithOpaqueBackground is silently overlaid with glass unless you also nil out backgroundEffect.

• UIBarAppearance.backgroundEffect = nil — required to actually get an opaque/transparent fill on iOS 26.
• UITabBarAppearance / UINavigationBarAppearance / UIToolbarAppearance — same backgroundEffect rule.
• Apple HIG: Adopt Liquid Glass
• WWDC25: "What's new in UIKit", "Build a UIKit app with the new design"

RNN handling:

• ios/BottomTabsAppearancePresenter.mm: branches on iOS 26 — uses configureWithTransparentBackground + backgroundEffect=nil + sets tabBar.backgroundColor. Pre-26 uses configureWithOpaqueBackground.
• ios/TopBarAppearancePresenter.mm: same pattern for the navigation bar.

2. Floating tab bar + drawBehind default

The tab bar floats above content on iOS 26 instead of pushing it up. Content underneath needs to extend.

• Tab bar no longer occupies layout space the same way; safeAreaInsets.bottom increases for content.
• Default drawBehind should be YES on iOS 26.

RNN handling:

• ios/RNNBottomTabsOptions.mm (-shouldDrawBehind): defaults drawBehind to YES on iOS 26, NO otherwise.
• ios/RNNBottomTabsController.mm: rnn_cycleAllTabsThenRestoreInitialSelection — iOS 26 first-layout bug where tab item titles get misplaced; cycle selection in viewDidAppear to force a correct layout. Gated by _rnnDidApplyInitialTabBarSelectionFix.

3. UITab / UITabBarController.tabs (iOS 18+, expanded in 26)

Modern tab API replaces viewControllers with tabs: [UITab]. Supports UITabGroup, UISearchTab, and UITabBarController.mode = .tabSidebar.

• UITab(title:image:identifier:viewControllerProvider:) — lazy VC creation per tab.
• UITabBarController.tabs — array of UITab, can mix UITab and UITabGroup.
• UITabBarController.mode — .tabBar (default) vs .tabSidebar (iPad sidebar).
• UISearchTab — first-class search tab, integrates with UINavigationItem search.
• UITabBarController.sidebarLayoutPreferences — iPad sidebar customization.
• UITabBarController.tabBarPlacement — .automatic, .bottom, .top (iPadOS 26 can pin the tab bar at the top of the window).
• Programmatic transitions between sidebar and tab bar layouts via animating mode changes inside UIView.animate.
• Apple: UITabBarController.tabs, UITab, UITabGroup

RNN handling: RNN currently uses the legacy viewControllers API. There is no UITab / tabs adoption yet. New iOS 26 tab features (sidebar mode, search tab, groups, top placement) would need a new code path in RNNBottomTabsController and corresponding Options.ts surface.

4. UITabBarController.bottomAccessory

Persistent floating mini-control attached above the tab bar (e.g., Apple Music's now-playing bar).

• UITabBarController.bottomAccessory: UITabAccessory?
• UITabAccessory(contentView:) — wraps a UIView.
• Apple: UITabAccessory

RNN handling: Not yet exposed. Would need a new option (e.g., bottomTabs.accessory: { component: { name, ... } }) and a presenter to mount a React view inside a UITabAccessory.

5. Scroll-edge appearance and effects

iOS 26 makes scrollEdgeAppearance matter more (the bar fades to transparent when scrolled to the top). New scrollEdgeEffect on UINavigationItem controls the effect.

• UINavigationItem.scrollEdgeEffect — controls the fading/glass effect at scroll edges.
• UINavigationBar.scrollEdgeAppearance — appearance when at the scroll edge.
• UITabBar.scrollEdgeAppearance — same for tab bar.
• Apple: UIScrollEdgeEffect (iOS 26)

RNN handling:

• scrollEdgeAppearance exposed via top bar options — see website/docs/api/options-scrollEdgeAppearance.mdx.
• iOS 26 scrollEdgeEffect added in PR #8281 (Add scrollEdgeEffect option).
• Title customization on scroll edge: PRs #8207, #8239.

6. Search bar placement (UINavigationItemSearchBarPlacement)

iOS 26 introduces three placements:

• UINavigationItemSearchBarPlacementStacked — under the title, classic.
• UINavigationItemSearchBarPlacementIntegrated — inline with the title bar, expanded.
• UINavigationItemSearchBarPlacementIntegratedButton — collapsed to a button until tapped.

Property: UINavigationItem.preferredSearchBarPlacement. Availability-gated, not present pre-iOS-26.

RNN handling:

• ios/RNNSearchBarPlacement.mm / .h — JS-facing enum.
• ios/UIViewController+RNNOptions.mm (setSearchBar...): maps RNN's SearchBarPlacementIntegrated to integrated or integrated-button depending on focus. Falls through to stacked otherwise.
• PR #8211 — skip integrated placement when not available (pre-26 safety).

7. Shared background ("Platter") on bar button items

iOS 26 wraps every UIBarButtonItem in a shared Liquid Glass platter. Custom views and pre-styled UIButtons get double-decorated.

• UIBarButtonItem.hidesSharedBackground: Bool — opt out of the platter.
• Custom views need a fixed bar-item size (44pt) so the navbar reserves the slot before React mounts the content; otherwise the navbar relayouts after mount and the custom view snaps into place.

RNN handling:

• ios/RNNUIBarButtonItem.mm: defaults hidesSharedBackground = YES on iOS 26 for both icon buttons and custom (React) view buttons. Pins custom view to 44x44.
• ios/RNNReactButtonView.mm: width/height constraints + center translation post-mount to keep the React view aligned inside the reserved 44pt slot.
• New option: RNNButtonOptions.hideSharedBackground (also on RNNBackButtonOptions) — see src/interfaces/Options.ts.
• PR #8300 — centering fix.

7a. UIBarButtonItemGroup factory APIs and prominent style (iOS 26)

iOS 26 added direct factories on UIBarButtonItem that build groups inline. These are the cleanest way to make the shared platter intentional rather than relying on UIKit's implicit clustering.

UIBarButtonItem.creatingFixedGroup() -> UIBarButtonItemGroup
UIBarButtonItem.creatingMovableGroup(customizationIdentifier:) -> UIBarButtonItemGroup
UIBarButtonItem.creatingOptionalGroup(customizationIdentifier:isInDefaultCustomization:) -> UIBarButtonItemGroup

Plus a new style:

• UIBarButtonItem.style = .prominent — primary-action styling, tints the platter with the bar's tintColor at full saturation. Use sparingly (one prominent item per bar).

When grouping is intentional, UIKit renders the group under a single _UIBarItemGroupPlatter (see §7b/§9) instead of one platter per item. hidesSharedBackground still applies per item, so you can mix glassed and bare items inside one group.

RNN handling: Not exposed today. If a future option models a logical action cluster, build it as a UIBarButtonItemGroup rather than a sequence of items so the platter coalesces correctly.

References:

• UIBarButtonItemGroup
• UIBarButtonItem.Style

7b. Internal view hierarchy: UIBarButtonItem on iOS 26

UIBarButtonItem is not a UIView — it's a model object. UIKit materializes it into a private view hierarchy inside the parent UINavigationBar or UIToolbar. The exact class names are private and can change; the layering and ordering are stable and worth knowing for layout debugging.

Approximate structure for a single bar button item (Liquid Glass, iOS 26):

UINavigationBar / UIToolbar
└── _UIBarBackground               (bar-wide background, Liquid Glass material)
└── _UIButtonBarStackView          (horizontal stack of items, leading or trailing group)
    └── _UIModernBarButton         (host view per item; one per UIBarButtonItem)
        ├── _UIBarItemPlatter      (shared Liquid Glass background; the "platter")
        │   └── CAFilter / glass layers (UIGlassEffect-backed)
        └── content view           (image, title label, OR customView)

Key facts that affect RNN code:

• The platter is per-item by default, but adjacent items inside the same UIBarButtonItemGroup (or implicit leading/trailing cluster) can be coalesced into a single shared platter spanning several items. This is the "shared background" that hidesSharedBackground opts out of.
• hidesSharedBackground = YES removes the _UIBarItemPlatter from the host view; the content view becomes the direct child of _UIModernBarButton. The host view is still 44pt minimum.
• The host view (_UIModernBarButton) reserves the slot, not the customView. UIKit sizes the host using:
  • System images: intrinsic size of the symbol + padding.
  • Title-only items: text width + padding.
  • Custom views: the customView's intrinsic content size at the time the bar performs layout. This is why RNN pins the custom React view to 44×44 in RNNUIBarButtonItem.mm — without explicit constraints, React mounts asynchronously, the customView's intrinsic size starts at zero, the host reserves zero width, the bar lays out, then React reports its real size and the host has to relayout. The visible artifact is the button "popping in" or being misplaced after the push transition's snapshot already captured the wrong frame.
• Transitions snapshot the bar. During push/pop, UIKit takes a snapshot of the navigation bar for the cross-fade between the from/to nav items. If the customView hasn't laid out before the snapshot, the snapshot shows the wrong state. This is also why a React customView can appear blank during a transition while being fine on the destination screen.
• Tinting flows through the platter, not the customView. tintColor set on the bar item or bar applies to the system image inside the host view; it does not propagate into a React customView. Color the React content explicitly.

Practical debugging:

• Inspect the live hierarchy with po [self.navigationItem.rightBarButtonItems.firstObject valueForKey:@"_view"] in lldb, or with View Debugger → uncheck "Show layers only" to see the private classes.
• A button that's "there but invisible" usually means the host view has 0×0 frame (sizing race) or hidesSharedBackground = NO with a customView that paints its own chrome (double-decoration clips/overlaps).
• A button that "snaps into place" after the screen appears means the host view's intrinsic size changed after the bar's first layout pass.

References (public API only — internals are observed, not documented):

• UIBarButtonItem
• UIBarButtonItem.hidesSharedBackground
• UIBarButtonItemGroup

8. Tab bar minimize behavior (iOS 26)

The tab bar can auto-minimize during scroll.

• UITabBarController.tabBarMinimizeBehavior — .automatic, .never, .onScrollDown, .onScrollUp.
• setNeedsUpdateOfTabBarMinimizeBehavior() — re-evaluate.
• Apple: UITabBarController

RNN handling: Not yet exposed. Would be a new option on bottomTabs.

9. UIToolbar on iOS 26

UIToolbar is a real UIView (unlike UIBarButtonItem). Approximate internal hierarchy on iOS 26:

UIToolbar
├── _UIBarBackground                  (bar-wide Liquid Glass material;
│                                      configured via UIToolbarAppearance)
│   └── _UIBackdropView / glass layers
│   └── _UIBarBackgroundShadowView    (1pt hairline; controlled by shadowImage / shadowColor)
└── _UIToolbarContentView
    └── _UIButtonBarStackView         (horizontal stack of toolbar items)
        ├── _UIModernBarButton        (item host — see 7b for layer breakdown)
        ├── _UIModernBarButton
        ├── ... fixed/flexible spaces become layout gaps in the stack ...
        └── (optional) _UIBarItemGroupPlatter
              └── two or more _UIModernBarButton sharing one platter
                  (only when items are in the same UIBarButtonItemGroup)

What's actually public and load-bearing on iOS 26:

• Appearance objects are the only safe way to style. UIToolbarAppearance (standard / compact / scrollEdge) drives _UIBarBackground. Setting barTintColor / backgroundImage on UIToolbar directly is silently overridden by Liquid Glass unless appearance.backgroundEffect = nil.
• Translucency is the default. configureWithDefaultBackground on iOS 26 produces glass. To get an opaque fill: configureWithOpaqueBackground plus backgroundEffect = nil plus explicit backgroundColor. This mirrors what BottomTabsAppearancePresenter.mm does for the tab bar.
• Items follow the same Platter rules as nav bar buttons. A custom view in a toolbar item gets wrapped in a platter unless hidesSharedBackground = YES. The 44pt host-view sizing race applies identically.
• Grouping with UIBarButtonItemGroup lets adjacent items render under one shared platter (visually grouped pill). customizationIdentifier opts the toolbar into the user-customization sheet (iPadOS).
• scrollEdgeAppearance matters here too. When a scroll view is attached, the toolbar fades to transparent at the scroll edge using UIToolbar.scrollEdgeAppearance. Pre-iOS-26 this was iPad-only for many cases; iOS 26 applies it consistently.

Display mode and customization (iOS 26 / iPadOS 26):

• UIToolbar.displayMode — .automatic, .expanded, .compact. Drives whether items spread out or collapse into an overflow menu.
• UIBarButtonItem.menuRepresentation — the menu UIKit shows when the item is hoisted into the overflow control under .compact.
• UIToolbar.beginCustomizingItems(...) / endCustomizingItems — programmatic entry into the user-customization sheet for movable/optional groups.

RNN handling:

RNN does not expose UIToolbar as a first-class options surface today. Toolbar-shaped behavior in this repo comes from the navigation controller's bottom bar via RNNStackController and is configured indirectly through stack options. Any new toolbar feature should:

1. Add a presenter (e.g. ToolbarPresenter) mirroring TopBarPresenter's appearance pattern.
2. Configure via UIToolbarAppearance only — never direct barTintColor / backgroundImage.
3. Use UIBarButtonItemGroup when the option models a logical cluster (e.g. "primary actions") so the platter coalesces correctly.
4. Apply hidesSharedBackground defaults for React custom views, same as RNNUIBarButtonItem.mm does today.

References:

• UIToolbar
• UIToolbarAppearance
• UIBarButtonItemGroup
• WWDC25: "What's new in UIKit" (toolbar/group section), "Build a UIKit app with the new design"

10. Preferred transition

• UINavigationController.preferredTransition — control push/pop animation style (iOS 26 expansion).
• UIViewController.preferredTransition — zoom transitions.

RNN handling: Not exposed. Stack push/pop currently uses defaults.

11. SF Symbols 7

iOS 26 ships SF Symbols 7. Bar buttons that use system images get the new variants automatically. Custom symbol configurations should re-test on iOS 26.

Animated symbols are part of the iOS 26 bar story:

• NSSymbolEffect family — .bounce, .pulse, .variableColor, .replace, .breathe, .scale, .appear, .disappear, .wiggle (iOS 18+; new variants in 26).
• Apply via the bar item's image: configure UIImageView produced by UIKit, or use UIView.addSymbolEffect(_:options:animated:) on the host view returned by UIBarButtonItem.value(forKey: "_view") (private — prefer using UIButton with a configured image inside a custom bar item).
• WWDC25: "What's new in SF Symbols 7".