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](https://developer.apple.com/design/human-interface-guidelines/materials) - 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](https://developer.apple.com/documentation/uikit/uitabbarcontroller/tabs), [UITab](https://developer.apple.com/documentation/uikit/uitab), [UITabGroup](https://developer.apple.com/documentation/uikit/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](https://developer.apple.com/documentation/uikit/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](https://developer.apple.com/documentation/uikit/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 `UIButton`s 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`](https://developer.apple.com/documentation/uikit/uibarbuttonitemgroup) - [`UIBarButtonItem.Style`](https://developer.apple.com/documentation/uikit/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`](https://developer.apple.com/documentation/uikit/uibarbuttonitem) - [`UIBarButtonItem.hidesSharedBackground`](https://developer.apple.com/documentation/uikit/uibarbuttonitem/hidessharedbackground) - [`UIBarButtonItemGroup`](https://developer.apple.com/documentation/uikit/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](https://developer.apple.com/documentation/uikit/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`](https://developer.apple.com/documentation/uikit/uitoolbar) - [`UIToolbarAppearance`](https://developer.apple.com/documentation/uikit/uitoolbarappearance) - [`UIBarButtonItemGroup`](https://developer.apple.com/documentation/uikit/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". ### 12. `UIButton` glass configurations `UIButton.Configuration` got first-class glass factories in iOS 26. Anything RNN renders that's *not* a bar button (custom views inside a screen, overlays, modal headers, bottom accessories) should adopt these instead of hand-rolling chrome. ``` UIButton.Configuration.glass() — translucent Liquid Glass pill UIButton.Configuration.prominentGlass() — tinted, more saturated variant UIButton.Configuration.plain() UIButton.Configuration.gray() UIButton.Configuration.tinted() UIButton.Configuration.filled() UIButton.Configuration.borderless() ``` On iOS 26 the legacy configurations (`plain` / `gray` / `tinted` / `filled` / `borderless`) automatically repaint with the Liquid Glass material — you don't opt in, you opt *out* via `UIDesignRequiresCompatibility`. Configuration knobs that affect build-up: - `cornerStyle` — `.fixed` / `.dynamic` / `.capsule` / `.small` / `.medium` / `.large`. `.dynamic` adopts concentric corners (see §15). - `buttonSize` — `.mini` / `.small` / `.medium` / `.large`.