feat(iOS, Stack v5): Add background and shadow appearance colors

[juliusmarminge]

Description

Stack v5's iOS appearance object exposes text attributes but cannot set the navigation bar's background or shadow colors. This adds UIKit's two related bar colors to the existing standard and scroll-edge appearance objects.

Changes

• Add optional ColorValue background and shadow colors to StackHeaderAppearanceIOS, with matching processed-color Fabric types and JS serialization.
• Convert both fields through RCTConvert UIColor in RNSStackHeaderAppearanceMapper. An explicit background replaces the default background material and preserves alpha and dynamic colors. Omitted fields preserve each appearance's UIKit defaults.
• Document the properties and add a standalone Stack v5 scenario with independent presets for defaults, empty appearances, opaque/transparent/translucent backgrounds, dynamic/platform colors, shadow-only customization and resets.

Existing appearance replacement creates fresh objects and clears the navigation-item appearance when omitted or empty, rather than retaining removed colors.

Before & after - visual documentation

Actual library base 7db05401d0d25f37143d875488c7a5a1b1720248 versus head e2eddbd5d2b28670ec811eaff0bf371039dccba8, using the same example, device, data and gestures on iOS 18.6. The new fields are ignored by the baseline.

Configuration	Before	After
Standard opaque background and red shadow, scrolled
Scroll-edge opaque background and red shadow, standard omitted
Standard transparent background and shadow, scrolled

Head: shadow-only restores the default background	Head: reset restores both defaults

Observed rendering limitation: after scrolling with an opaque standard appearance, selecting a transparent scroll-edge appearance leaves the standard sky-blue background visible at the top on iOS 18.6 and 26.5, while its shadow disappears. A live UIKit inspection confirmed clear edge background/shadow properties and the registered scroll view at its adjusted top inset. Edge-only opaque and transparent colors work with standard omitted. This mixed combination still needs UIKit/maintainer investigation; I am not claiming complete visual independence for it. The PR preserves automatic scroll-edge effects.

Test plan

Run TestStackHeaderBarColorsIOS from apps/App.tsx, or select Stack Header Bar Colors (iOS) in the Stack v5 scenarios. Follow the included scenario.md to compare standard and scroll-edge presets and remove/reset properties.

Local validation:

• Library yarn check-types, focused example type check, and yarn prepare CommonJS/module/declaration builds passed.
• iOS and Android codegen passed; the example's Android Metro bundle compiled. Native Android, web and tvOS runtime builds were not run.
• ESLint passed with 18 existing library warnings and no errors; changed files have no warnings. Prettier, clang-format and git diff --check passed. React Doctor scored 100/100.
• FabricExample built with Xcode 27.1 / iOS 27.1 SDK. Five hosted native XCTest cases passed on both iOS 18.6 and 26.5: both appearance constructors, omitted defaults, transparent/translucent colors, dynamic/platform color trait resolution, and replacement/reset. On the actual base, only the defaults case passed; the four color cases failed as expected.
• The UI flow passed on both runtimes and captured the states above. It asserts controls and collapsed/expanded bar states; color assertions are in the native tests and screenshots were inspected manually. The mixed appearance limitation above remains a review gate.

Native test sources, original result summaries and reproduction notes. The temporary test-target setup and evidence are outside git.

CI is currently blocked on maintainer approval for all seven GitHub Actions workflows. The CI checklist remains unchecked. CodeRabbit completed with no actionable inline comments; its function-docstring coverage warning is addressed in the review follow-up comment.

Downstream API gate

The contribution guide requests a React Navigation companion for new APIs. Native-stack at current React Navigation main still uses v4 ScreenStack / ScreenStackItem, as does Screens' pinned submodule. It has no Stack v5 appearance option to extend. Current v4 consumers are unaffected.

A separate focused companion proposal is prepared for the v5 consumer. Maintainers need to confirm deferral until v5 adoption or identify an active downstream v5 branch to receive it. No downstream implementation PR has been opened, and this policy gate remains outstanding.

Checklist

• Included code example that can be used to test this change.
• For visual changes, included screenshots / GIFs / recordings documenting the change.
• For API changes, updated relevant public types.
• Ensured that CI passes

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 3cf41aae-1aeb-45f7-adb4-b8b929b76bef

📥 Commits

Reviewing files that changed from the base of the PR and between 7db0540 and e2eddbd.

📒 Files selected for processing (8)

• apps/src/tests/single-feature-tests/stack-v5/index.ts
• apps/src/tests/single-feature-tests/stack-v5/test-stack-header-bar-colors-ios/index.tsx
• apps/src/tests/single-feature-tests/stack-v5/test-stack-header-bar-colors-ios/scenario-description.ts
• apps/src/tests/single-feature-tests/stack-v5/test-stack-header-bar-colors-ios/scenario.md
• ios/stack/header/RNSStackHeaderAppearanceMapper.mm
• src/components/stack/header/StackHeaderConfig.ios.tsx
• src/components/stack/header/StackHeaderConfig.ios.types.ts
• src/fabric/stack/StackHeaderConfigIOSNativeComponent.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds iOS header background and shadow color support for standard and scroll-edge appearances. It updates public types, JavaScript-to-native color mapping, UIKit appearance handling, and adds a registered manual test scenario.

Changes

iOS Header Bar Colors

Layer / File(s)	Summary
Appearance contract and color mapping src/components/stack/header/*, src/fabric/stack/StackHeaderConfigIOSNativeComponent.ts	The iOS appearance types and native component accept optional background and shadow colors. The JavaScript mapper processes both colors.
UIKit appearance application ios/stack/header/RNSStackHeaderAppearanceMapper.mm	The mapper applies background and shadow colors to standard and scroll-edge navigation bar appearances.
Scenario registration and validation apps/src/tests/single-feature-tests/stack-v5/*	A selectable iOS scenario tests appearance presets, independent scroll-edge settings, reset behavior, and documented manual verification steps.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant TestScenario
  participant StackHeaderConfig
  participant RNSStackHeaderAppearanceMapper
  participant UINavigationBarAppearance
  TestScenario->>StackHeaderConfig: select standard or scroll-edge colors
  StackHeaderConfig->>RNSStackHeaderAppearanceMapper: pass processed appearance values
  RNSStackHeaderAppearanceMapper->>UINavigationBarAppearance: apply background and shadow colors

Loading

Suggested reviewers: kmichalikk

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 6 files. (2 skipped: 2 …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding iOS Stack v5 background and shadow appearance colors.
Description check	✅ Passed	The description directly explains the new API properties, native implementation, scenarios, validation, and known limitation. It is fully related to the changeset.

Full details: Docstring Coverage

Explanation

Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 6 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[juliusmarminge]

Reviewed CodeRabbit's result for e2eddbd5d2b28670ec811eaff0bf371039dccba8. It generated no actionable inline comments or review threads.

The function-docstring coverage warning does not measure the new public appearance properties. Both properties have summary, behavior/default and platform documentation in StackHeaderAppearanceIOS. The native helper also explains material removal and dynamic-color preservation inline. Private serialization helpers and scenario components follow the neighboring code's style, so I am retaining those concise docs rather than adding comments that repeat the component logic solely for the function-coverage metric.

All seven GitHub Actions workflows require maintainer approval and have not run. The CI checklist remains unchecked. The mixed opaque-standard/transparent-edge rendering observation and the downstream companion policy gate are still disclosed in the description; passing mapper assertions and the CodeRabbit status do not clear those gates.