From 65835976f57ee743e4c6fc90cd06424831684a8f Mon Sep 17 00:00:00 2001
From: Konrad Michalik <konrad.michalik@swmansion.com>
Date: Fri, 3 Jul 2026 13:42:13 +0200
Subject: [PATCH 1/6] feat(Stack v5, iOS): Support icon loading in header items
 and menu

---
 .../single-feature-tests/stack-v5/index.ts    |   3 +
 .../test-stack-header-icon-ios/index.tsx      | 248 ++++++++++++++++++
 .../scenario-description.ts                   |  11 +
 .../RNSStackHeaderConfigComponentDescriptor.h |   7 +
 .../RNSStackHeaderConfigShadowNode.cpp        |  12 +
 .../RNSStackHeaderConfigShadowNode.h          |   3 +
 .../rnscreens/RNSStackHeaderConfigState.cpp   |   9 +
 .../rnscreens/RNSStackHeaderConfigState.h     |   6 +
 .../RNSStackHeaderConfigComponentView.h       |   4 +-
 .../RNSStackHeaderConfigComponentView.mm      |  26 ++
 .../header/RNSStackHeaderContentFactory.h     |   4 +-
 .../header/RNSStackHeaderContentFactory.mm    |  36 ++-
 .../stack/header/RNSStackHeaderIconData.h     |  28 ++
 .../stack/header/RNSStackHeaderIconData.mm    |  17 ++
 .../stack/header/RNSStackHeaderIconMapper.h   |  15 ++
 .../stack/header/RNSStackHeaderIconMapper.mm  |  52 ++++
 .../stack/header/RNSStackHeaderIconResolver.h |  25 ++
 .../header/RNSStackHeaderIconResolver.mm      |  50 ++++
 .../header/RNSStackHeaderItemComponentView.h  |   1 +
 .../header/RNSStackHeaderItemComponentView.mm |   8 +
 .../header/RNSStackHeaderItemDataProviding.h  |   2 +
 .../header/RNSStackHeaderMenuCoordinator.h    |  11 +-
 .../header/RNSStackHeaderMenuCoordinator.mm   |  75 +++++-
 .../stack/header/RNSStackHeaderMenuData.h     |  10 +-
 .../stack/header/RNSStackHeaderMenuData.mm    |   4 +
 .../stack/header/RNSStackHeaderMenuMapper.mm  |  17 +-
 .../screen/RNSStackScreenHeaderCoordinator.h  |   2 +
 .../screen/RNSStackScreenHeaderCoordinator.mm |  17 +-
 ios/helpers/image/RNSImageLoading.h           |  15 ++
 .../header/StackHeaderConfig.ios.types.ts     |  12 +
 src/components/gamma/stack/header/index.ts    |   2 +
 .../stack/header/ios/StackHeaderItem.ios.tsx  |  61 ++++-
 .../header/ios/StackHeaderItem.ios.types.ts   |   2 +
 .../header/ios/StackHeaderMenu.ios.types.ts   |  22 ++
 .../StackHeaderItemIOSNativeComponent.ts      |   5 +
 35 files changed, 783 insertions(+), 39 deletions(-)
 create mode 100644 apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx
 create mode 100644 apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario-description.ts
 create mode 100644 ios/gamma/stack/header/RNSStackHeaderIconData.h
 create mode 100644 ios/gamma/stack/header/RNSStackHeaderIconData.mm
 create mode 100644 ios/gamma/stack/header/RNSStackHeaderIconMapper.h
 create mode 100644 ios/gamma/stack/header/RNSStackHeaderIconMapper.mm
 create mode 100644 ios/gamma/stack/header/RNSStackHeaderIconResolver.h
 create mode 100644 ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
 create mode 100644 ios/helpers/image/RNSImageLoading.h

diff --git a/apps/src/tests/single-feature-tests/stack-v5/index.ts b/apps/src/tests/single-feature-tests/stack-v5/index.ts
index f8dd9a5e45..426bd4e3fe 100644
--- a/apps/src/tests/single-feature-tests/stack-v5/index.ts
+++ b/apps/src/tests/single-feature-tests/stack-v5/index.ts
@@ -9,6 +9,7 @@ import TestStackSimpleNav from './test-stack-simple-nav';
 import TestStackSubviewsAndroid from './test-stack-subviews-android';
 import TestStackSubviewsIOS from './test-stack-subviews-ios';
 import TestStackHeaderMenuIOS from './test-stack-header-menu-ios';
+import TestStackHeaderIconIOS from './test-stack-header-icon-ios';
 import TestStackBackButton from './test-stack-back-button-android';
 import TestStackToolbarMenuCommands from './test-stack-toolbar-menu-commands-android';
 import TestStackToolbarMenuDisabled from './test-stack-toolbar-menu-disabled-android';
@@ -29,6 +30,7 @@ export { default as TestStackSimpleNav } from './test-stack-simple-nav';
 export { default as TestStackSubviewsAndroid } from './test-stack-subviews-android';
 export { default as TestStackSubviewsIOS } from './test-stack-subviews-ios';
 export { default as TestStackHeaderMenuIOS } from './test-stack-header-menu-ios';
+export { default as TestStackHeaderIconIOS } from './test-stack-header-icon-ios';
 export { default as TestStackBackButton } from './test-stack-back-button-android';
 export { default as TestStackToolbarMenuCommands } from './test-stack-toolbar-menu-commands-android';
 export { default as TestStackToolbarMenuDisabled } from './test-stack-toolbar-menu-disabled-android';
@@ -46,6 +48,7 @@ const scenarios = {
   TestStackSubviewsAndroid,
   TestStackSubviewsIOS,
   TestStackHeaderMenuIOS,
+  TestStackHeaderIconIOS,
   TestStackHeaderSubviewOnPress,
   TestStackHeaderSelectiveUpdates,
   TestStackBackButton,
diff --git a/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx
new file mode 100644
index 0000000000..cc513f90fa
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx
@@ -0,0 +1,248 @@
+import React, { useCallback, useLayoutEffect, useMemo, useState } from 'react';
+import { createScenario } from '@apps/tests/shared/helpers';
+import {
+  StackContainer,
+  useStackNavigationContext,
+} from '@apps/shared/gamma/containers/stack';
+import {
+  StackHeaderConfigProps,
+  PlatformIconIOS,
+} from 'react-native-screens/components/gamma/stack/header';
+import { Button, ScrollView, Text, View, StyleSheet } from 'react-native';
+import { scenarioDescription } from './scenario-description';
+import { ToastProvider, useToast } from '@apps/shared';
+import { Colors } from '@apps/shared/styling';
+
+type IconVariant = 'sfSymbol' | 'xcasset' | 'imageSource' | 'templateSource';
+
+const ICON_VARIANTS: IconVariant[] = [
+  'sfSymbol',
+  'xcasset',
+  'imageSource',
+  'templateSource',
+];
+
+function iconForVariant(variant: IconVariant): PlatformIconIOS {
+  switch (variant) {
+    case 'sfSymbol':
+      return { type: 'sfSymbol', name: 'star.fill' };
+    case 'xcasset':
+      return { type: 'xcasset', name: 'custom-icon-fill' };
+    case 'imageSource':
+      return {
+        type: 'imageSource',
+        imageSource: require('@assets/search_black.png'),
+      };
+    case 'templateSource':
+      return {
+        type: 'templateSource',
+        templateSource: require('@assets/variableIcons/icon.png'),
+      };
+  }
+}
+
+function nextVariant(current: IconVariant): IconVariant {
+  const idx = ICON_VARIANTS.indexOf(current);
+  return ICON_VARIANTS[(idx + 1) % ICON_VARIANTS.length]!;
+}
+
+function buildHeaderConfig(
+  itemIconVariant: IconVariant,
+  menuIconVariant: IconVariant,
+  cycleMenuIcons: () => void,
+  showToast: (text: string) => void,
+): StackHeaderConfigProps {
+  const itemIcon = iconForVariant(itemIconVariant);
+  const menuIcon = iconForVariant(menuIconVariant);
+
+  return {
+    title: 'Header Icons',
+    ios: {
+      trailingItems: [
+        {
+          type: 'item',
+          id: 'icon-item',
+          title: 'Actions',
+          icon: itemIcon,
+          onPress: () => showToast('Item pressed'),
+          menu: {
+            type: 'menu',
+            id: 'main-menu',
+            onSelectionChange: selection =>
+              showToast('Selected: ' + selection.join(', ')),
+            children: [
+              {
+                id: 'cycle-action',
+                type: 'menuItem',
+                itemType: 'action',
+                title: `Cycle icons (${menuIconVariant})`,
+                keepsMenuPresented: true,
+                onPress: cycleMenuIcons,
+              },
+              {
+                id: 'toggle-1',
+                type: 'menuItem',
+                itemType: 'toggle',
+                title: 'Toggle 1',
+                icon: menuIcon,
+                keepsMenuPresented: true,
+              },
+              {
+                id: 'toggle-2',
+                type: 'menuItem',
+                itemType: 'toggle',
+                title: 'Toggle 2',
+                icon: menuIcon,
+                keepsMenuPresented: true,
+              },
+              {
+                id: 'toggle-3',
+                type: 'menuItem',
+                itemType: 'toggle',
+                title: 'Toggle 3',
+                icon: menuIcon,
+                keepsMenuPresented: true,
+              },
+              {
+                id: 'submenu',
+                type: 'menu',
+                title: 'Submenu',
+                icon: menuIcon,
+                children: [
+                  {
+                    id: 'sub-toggle-1',
+                    type: 'menuItem',
+                    itemType: 'toggle',
+                    title: 'Sub Toggle 1',
+                    icon: menuIcon,
+                    keepsMenuPresented: true,
+                  },
+                  {
+                    id: 'sub-toggle-2',
+                    type: 'menuItem',
+                    itemType: 'toggle',
+                    title: 'Sub Toggle 2',
+                    icon: menuIcon,
+                    keepsMenuPresented: true,
+                  },
+                  {
+                    id: 'sub-toggle-3',
+                    type: 'menuItem',
+                    itemType: 'toggle',
+                    title: 'Sub Toggle 3',
+                    icon: menuIcon,
+                    keepsMenuPresented: true,
+                  },
+                ],
+              },
+            ],
+          },
+        },
+      ],
+    },
+  };
+}
+
+function ConfigScreen() {
+  const navigation = useStackNavigationContext();
+  const toast = useToast();
+
+  const [itemIconVariant, setItemIconVariant] =
+    useState<IconVariant>('sfSymbol');
+  const [menuIconVariant, setMenuIconVariant] =
+    useState<IconVariant>('sfSymbol');
+
+  const showToast = useCallback(
+    (text: string) => {
+      toast.push({ backgroundColor: Colors.GreenDark120, message: text });
+    },
+    [toast],
+  );
+
+  const cycleMenuIcons = useCallback(() => {
+    setMenuIconVariant(v => nextVariant(v));
+  }, []);
+
+  const { setRouteOptions, routeKey } = navigation;
+  const headerConfig = useMemo(
+    () =>
+      buildHeaderConfig(
+        itemIconVariant,
+        menuIconVariant,
+        cycleMenuIcons,
+        showToast,
+      ),
+    [itemIconVariant, menuIconVariant, cycleMenuIcons, showToast],
+  );
+
+  useLayoutEffect(() => {
+    setRouteOptions(routeKey, {
+      headerConfig,
+    });
+  }, [headerConfig, setRouteOptions, routeKey]);
+
+  return (
+    <ScrollView
+      contentInsetAdjustmentBehavior="automatic"
+      style={styles.container}>
+      <View style={styles.section}>
+        <Text style={styles.label}>Bar Button Item Icon</Text>
+        <Text style={styles.current}>{itemIconVariant}</Text>
+        <Button
+          title="Cycle item icon"
+          onPress={() => setItemIconVariant(nextVariant)}
+        />
+      </View>
+      <View style={styles.section}>
+        <Text style={styles.label}>Menu Toggles + Submenu Icon</Text>
+        <Text style={styles.current}>{menuIconVariant}</Text>
+        <Button title="Cycle menu icons" onPress={cycleMenuIcons} />
+      </View>
+      <View style={styles.section}>
+        <Button
+          title="Push screen with same config"
+          onPress={() => navigation.push('Home')}
+        />
+      </View>
+    </ScrollView>
+  );
+}
+
+function TestStackHeaderIconIOS() {
+  return (
+    <ToastProvider>
+      <StackContainer
+        routeConfigs={[
+          {
+            name: 'Home',
+            Component: ConfigScreen,
+            options: {},
+          },
+        ]}
+      />
+    </ToastProvider>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  section: {
+    padding: 16,
+    borderBottomWidth: StyleSheet.hairlineWidth,
+    borderBottomColor: '#ccc',
+  },
+  label: {
+    fontSize: 14,
+    fontWeight: '600',
+    marginBottom: 4,
+  },
+  current: {
+    fontSize: 16,
+    marginBottom: 8,
+    color: Colors.GreenDark120,
+  },
+});
+
+export default createScenario(TestStackHeaderIconIOS, scenarioDescription);
diff --git a/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario-description.ts b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario-description.ts
new file mode 100644
index 0000000000..35966aa701
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario-description.ts
@@ -0,0 +1,11 @@
+import type { ScenarioDescription } from '@apps/tests/shared/helpers';
+
+export const scenarioDescription: ScenarioDescription = {
+  name: 'Stack Header Icon (iOS)',
+  key: 'test-stack-header-icon-ios',
+  details:
+    'Tests header item icons: SF Symbol, xcasset, imageSource, templateSource on bar button items and menu items, with runtime updates.',
+  platforms: ['ios'],
+  e2eCoverage: 'tbd',
+  smokeTest: false,
+};
diff --git a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigComponentDescriptor.h b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigComponentDescriptor.h
index a70ae40c7d..811c0a3be4 100644
--- a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigComponentDescriptor.h
+++ b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigComponentDescriptor.h
@@ -35,6 +35,13 @@ class RNSStackHeaderConfigComponentDescriptor final
       layoutableShadowNode.setSize(
           Size{stateData.frameSize.width, stateData.frameSize.height});
     }
+
+#if !defined(ANDROID)
+    std::weak_ptr<void> imageLoader =
+        contextContainer_->at<std::shared_ptr<void>>("RCTImageLoader");
+    configShadowNode.setImageLoader(imageLoader);
+#endif // !defined(ANDROID)
+
     ConcreteComponentDescriptor::adopt(shadowNode);
   }
 };
diff --git a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.cpp b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.cpp
index 6fa2341840..298b9c1fa9 100644
--- a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.cpp
+++ b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.cpp
@@ -29,5 +29,17 @@ void RNSStackHeaderConfigShadowNode::applyFrameCorrections() {
   layoutMetrics_.frame.origin.x = stateData.contentOffset.x;
   layoutMetrics_.frame.origin.y = stateData.contentOffset.y;
 }
+
+void RNSStackHeaderConfigShadowNode::setImageLoader(
+    std::weak_ptr<void> imageLoader) {
+  getStateDataMutable().setImageLoader(imageLoader);
+}
+
+RNSStackHeaderConfigShadowNode::StateData &
+RNSStackHeaderConfigShadowNode::getStateDataMutable() {
+  ensureUnsealed();
+  return const_cast<RNSStackHeaderConfigShadowNode::StateData &>(
+      getStateData());
+}
 #endif // ANDROID
 } // namespace facebook::react
diff --git a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.h b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.h
index 10e40576be..99d25eb502 100644
--- a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.h
+++ b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigShadowNode.h
@@ -31,8 +31,11 @@ class JSI_EXPORT RNSStackHeaderConfigShadowNode final
 #else // ANDROID
   void layout(LayoutContext layoutContext) override;
 
+  void setImageLoader(std::weak_ptr<void> imageLoader);
+
  private:
   void applyFrameCorrections();
+  StateData &getStateDataMutable();
 #endif // ANDROID
 };
 
diff --git a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.cpp b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.cpp
index 9db860c70a..0163eed7a6 100644
--- a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.cpp
+++ b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.cpp
@@ -2,6 +2,15 @@
 
 namespace facebook::react {
 
+void RNSStackHeaderConfigState::setImageLoader(
+    std::weak_ptr<void> imageLoader) {
+  imageLoader_ = imageLoader;
+}
+
+std::weak_ptr<void> RNSStackHeaderConfigState::getImageLoader() const noexcept {
+  return imageLoader_;
+}
+
 #ifdef ANDROID
 folly::dynamic RNSStackHeaderConfigState::getDynamic() const {
   return folly::dynamic::object("frameWidth", frameSize.width)(
diff --git a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.h b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.h
index 9b438c9bd5..37f37ccbc0 100644
--- a/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.h
+++ b/common/cpp/react/renderer/components/rnscreens/RNSStackHeaderConfigState.h
@@ -21,6 +21,9 @@ class JSI_EXPORT RNSStackHeaderConfigState final {
   Size frameSize{};
   Point contentOffset{};
 
+  void setImageLoader(std::weak_ptr<void> imageLoader);
+  std::weak_ptr<void> getImageLoader() const noexcept;
+
 #ifdef ANDROID
   RNSStackHeaderConfigState(
       RNSStackHeaderConfigState const &previousState,
@@ -42,6 +45,9 @@ class JSI_EXPORT RNSStackHeaderConfigState final {
   RNSStackHeaderConfigState(Size frameSize_, Point contentOffset_)
       : frameSize(frameSize_), contentOffset(contentOffset_) {};
 #endif // ANDROID
+
+ private:
+  std::weak_ptr<void> imageLoader_;
 };
 
 } // namespace facebook::react
diff --git a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.h b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.h
index 999c4a8511..f0b8aae2c5 100644
--- a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.h
+++ b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.h
@@ -1,5 +1,6 @@
 #pragma once
 
+#import "RNSImageLoading.h"
 #import "RNSReactBaseView.h"
 #import "RNSStackHeaderConfigDataProviding.h"
 #import "RNSStackHeaderEventsDelegate.h"
@@ -11,7 +12,8 @@ NS_ASSUME_NONNULL_BEGIN
 @interface RNSStackHeaderConfigComponentView : RNSReactBaseView <RNSViewFrameChangeDelegate,
                                                                  RNSStackHeaderConfigDataProviding,
                                                                  RNSStackHeaderItemInvalidationDelegate,
-                                                                 RNSStackHeaderEventsDelegate>
+                                                                 RNSStackHeaderEventsDelegate,
+                                                                 RNSImageLoading>
 
 @property (nonatomic, readonly, nullable) NSString *title;
 @property (nonatomic, readonly, nullable) NSString *subtitle;
diff --git a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
index abc62d9084..0b2ba63cb0 100644
--- a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
@@ -1,4 +1,5 @@
 #import "RNSStackHeaderConfigComponentView.h"
+#import "RNSImageLoadingHelper.h"
 #import "RNSLog.h"
 #import "RNSStackHeaderConfigEventEmitter.h"
 #import "RNSStackHeaderConfigShadowStateProxy.h"
@@ -10,8 +11,10 @@
 #import "RNSStackScreenHeaderCoordinator.h"
 
 #import <React/RCTConversions.h>
+#import <React/RCTImageLoader.h>
 #import <react/renderer/components/rnscreens/Props.h>
 #import <react/renderer/components/rnscreens/RCTComponentViewHelpers.h>
+#import <react/utils/ManagedObjectWrapper.h>
 #import <rnscreens/RNSStackHeaderConfigComponentDescriptor.h>
 
 namespace react = facebook::react;
@@ -31,6 +34,7 @@ @implementation RNSStackHeaderConfigComponentView {
   RNSStackHeaderConfigShadowStateProxy *_Nonnull _shadowStateProxy;
   RNSStackHeaderConfigEventEmitter *_Nonnull _reactEventEmitter;
   NSMutableArray<id> *_children;
+  RCTImageLoader *_imageLoader;
 }
 
 - (instancetype)initWithFrame:(CGRect)frame
@@ -61,6 +65,23 @@ - (void)resetProps
   return [_children copy];
 }
 
+#pragma mark - RNSImageLoading
+
+- (void)loadImageFromJsonSource:(NSDictionary *)jsonSource
+                     asTemplate:(BOOL)isTemplate
+         withCompletionCallback:(void (^)(UIImage *image))completionBlock
+{
+  RCTAssert(_imageLoader != nil, @"[RNScreens] imageLoader must not be nil when loading images");
+
+  RCTImageSource *imageSource = [RCTConvert RCTImageSource:jsonSource];
+  RCTAssert(imageSource != nil, @"[RNScreens] Expected nonnil image source");
+
+  [RNSImageLoadingHelper loadImageFromSource:imageSource
+                             withImageLoader:_imageLoader
+                                  asTemplate:isTemplate
+                             completionBlock:completionBlock];
+}
+
 #pragma mark - UIView
 
 - (UIView *)hitTest:(CGPoint)point withEvent:(UIEvent *)event
@@ -88,12 +109,14 @@ - (void)didMoveToWindow
     coordinator.configDataProvider = self;
     coordinator.frameChangeDelegate = self;
     coordinator.eventsDelegate = self;
+    coordinator.imageLoader = self;
     [coordinator rebuild];
   } else {
     RNSStackScreenHeaderCoordinator *coordinator = [self headerCoordinator];
     coordinator.configDataProvider = nil;
     coordinator.frameChangeDelegate = nil;
     coordinator.eventsDelegate = nil;
+    coordinator.imageLoader = nil;
   }
   [super didMoveToWindow];
 }
@@ -209,6 +232,9 @@ - (void)viewFrameDidChange:(nonnull UINavigationBar *)navigationBar
 - (void)updateState:(const react::State::Shared &)state oldState:(const react::State::Shared &)oldState
 {
   _state = std::static_pointer_cast<const react::RNSStackHeaderConfigShadowNode::ConcreteState>(state);
+  if (auto imgLoaderPtr = _state.get()->getData().getImageLoader().lock()) {
+    _imageLoader = react::unwrapManagedObject(imgLoaderPtr);
+  }
 }
 
 - (react::RNSStackHeaderConfigShadowNode::ConcreteState::Shared)state
diff --git a/ios/gamma/stack/header/RNSStackHeaderContentFactory.h b/ios/gamma/stack/header/RNSStackHeaderContentFactory.h
index 7057e5ff37..c1c75ecf13 100644
--- a/ios/gamma/stack/header/RNSStackHeaderContentFactory.h
+++ b/ios/gamma/stack/header/RNSStackHeaderContentFactory.h
@@ -2,6 +2,7 @@
 
 #import <UIKit/UIKit.h>
 
+#import "RNSImageLoading.h"
 #import "RNSStackHeaderEventsDelegate.h"
 #import "RNSStackHeaderItemDataProviding.h"
 #import "RNSStackHeaderItemSpacerDataProviding.h"
@@ -19,7 +20,8 @@ NS_ASSUME_NONNULL_BEGIN
  */
 + (UIBarButtonItem *)barButtonItemForHeaderItem:(id<RNSStackHeaderItemDataProviding>)item
                         withFrameChangeDelegate:(id<RNSViewFrameChangeDelegate>)delegate
-                       withHeaderEventsDelegate:(id<RNSStackHeaderEventsDelegate>)headerEventsDelegate;
+                       withHeaderEventsDelegate:(id<RNSStackHeaderEventsDelegate>)headerEventsDelegate
+                                withImageLoader:(id<RNSImageLoading>)imageLoader;
 
 /**
  Builds views that can be added to other areas of the header: titleView, subtitleView, largeSubtitleView.
diff --git a/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm b/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
index 30bf50d6a9..1c67494792 100644
--- a/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
@@ -1,5 +1,7 @@
 #import "RNSStackHeaderContentFactory.h"
 #import "RNSDefines.h"
+#import "RNSLog.h"
+#import "RNSStackHeaderIconResolver.h"
 #import "RNSStackHeaderItemWrapperView.h"
 #import "RNSStackHeaderMenuCoordinator.h"
 
@@ -8,6 +10,7 @@ @implementation RNSStackHeaderContentFactory
 + (UIBarButtonItem *)barButtonItemForHeaderItem:(id<RNSStackHeaderItemDataProviding>)item
                         withFrameChangeDelegate:(id<RNSViewFrameChangeDelegate>)delegate
                        withHeaderEventsDelegate:(id<RNSStackHeaderEventsDelegate>)headerEventsDelegate
+                                withImageLoader:(id<RNSImageLoading>)imageLoader
 {
   if (item.customView != nil) {
 #if RNS_IPHONE_OS_VERSION_AVAILABLE(26_0)
@@ -21,6 +24,16 @@ + (UIBarButtonItem *)barButtonItemForHeaderItem:(id<RNSStackHeaderItemDataProvid
                                                                   frameChangeDelegate:delegate]];
   }
 
+  return [self labelBarButtonItemForHeaderItem:item
+                      withHeaderEventsDelegate:headerEventsDelegate
+                               withImageLoader:imageLoader];
+}
+
++ (UIBarButtonItem *)labelBarButtonItemForHeaderItem:(id<RNSStackHeaderItemDataProviding>)item
+                            withHeaderEventsDelegate:(id<RNSStackHeaderEventsDelegate>)headerEventsDelegate
+                                     withImageLoader:(id<RNSImageLoading>)imageLoader
+{
+  UIBarButtonItem *barButtonItem;
   if (item.respondsToOnPress) {
     __weak id<RNSStackHeaderEventsDelegate> weakDelegate = headerEventsDelegate;
     NSString *itemId = item.itemId;
@@ -30,10 +43,29 @@ + (UIBarButtonItem *)barButtonItemForHeaderItem:(id<RNSStackHeaderItemDataProvid
                                               handler:^(__kindof UIAction *_Nonnull action) {
                                                 [weakDelegate didPressHeaderItem:itemId];
                                               }];
-    return [[UIBarButtonItem alloc] initWithPrimaryAction:pressAction];
+    barButtonItem = [[UIBarButtonItem alloc] initWithPrimaryAction:pressAction];
+  } else {
+    barButtonItem = [[UIBarButtonItem alloc] initWithTitle:item.title
+                                                     style:UIBarButtonItemStylePlain
+                                                    target:nil
+                                                    action:nil];
+  }
+
+  if (item.icon != nil) {
+    __weak UIBarButtonItem *weakBarButtonItem = barButtonItem;
+    UIImage *syncImage = [RNSStackHeaderIconResolver resolveIcon:item.icon
+                                                 withImageLoader:imageLoader
+                                            asyncCompletionBlock:^(UIImage *_Nullable image) {
+                                              if (weakBarButtonItem == nil) {
+                                                RNSLog(@"[RNScreens] Attempt to set image on nil UIBarButtonItem");
+                                                return;
+                                              }
+                                              weakBarButtonItem.image = image;
+                                            }];
+    barButtonItem.image = syncImage ? syncImage : [UIImage imageWithCIImage:[CIImage emptyImage]];
   }
 
-  return [[UIBarButtonItem alloc] initWithTitle:item.title style:UIBarButtonItemStylePlain target:nil action:nil];
+  return barButtonItem;
 }
 
 + (UIView *)wrappedViewForHeaderItem:(id<RNSStackHeaderItemDataProviding>)item
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconData.h b/ios/gamma/stack/header/RNSStackHeaderIconData.h
new file mode 100644
index 0000000000..7c3c5cc15c
--- /dev/null
+++ b/ios/gamma/stack/header/RNSStackHeaderIconData.h
@@ -0,0 +1,28 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+typedef NS_ENUM(NSInteger, RNSStackHeaderIconType) {
+  RNSStackHeaderIconTypeSfSymbol,
+  RNSStackHeaderIconTypeXcasset,
+  RNSStackHeaderIconTypeImageSource,
+  RNSStackHeaderIconTypeTemplateSource,
+};
+
+@interface RNSStackHeaderIconData : NSObject
+
+@property (nonatomic, readonly) RNSStackHeaderIconType iconType;
+@property (nonatomic, copy, readonly, nullable) NSString *resourceName;
+@property (nonatomic, copy, readonly, nullable) NSDictionary *jsonSource;
+@property (nonatomic, strong, nullable) UIImage *resolvedImage;
+
+- (instancetype)initWithType:(RNSStackHeaderIconType)iconType
+                resourceName:(nullable NSString *)resourceName
+                  jsonSource:(nullable NSDictionary *)jsonSource;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconData.mm b/ios/gamma/stack/header/RNSStackHeaderIconData.mm
new file mode 100644
index 0000000000..834a136022
--- /dev/null
+++ b/ios/gamma/stack/header/RNSStackHeaderIconData.mm
@@ -0,0 +1,17 @@
+#import "RNSStackHeaderIconData.h"
+
+@implementation RNSStackHeaderIconData
+
+- (instancetype)initWithType:(RNSStackHeaderIconType)iconType
+                resourceName:(nullable NSString *)resourceName
+                  jsonSource:(nullable NSDictionary *)jsonSource
+{
+  if (self = [super init]) {
+    _iconType = iconType;
+    _resourceName = [resourceName copy];
+    _jsonSource = [jsonSource copy];
+  }
+  return self;
+}
+
+@end
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconMapper.h b/ios/gamma/stack/header/RNSStackHeaderIconMapper.h
new file mode 100644
index 0000000000..385f1edc95
--- /dev/null
+++ b/ios/gamma/stack/header/RNSStackHeaderIconMapper.h
@@ -0,0 +1,15 @@
+#pragma once
+
+#import <Foundation/Foundation.h>
+
+#import "RNSStackHeaderIconData.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface RNSStackHeaderIconMapper : NSObject
+
++ (nullable RNSStackHeaderIconData *)iconFromDictionary:(nullable id)dictionary;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconMapper.mm b/ios/gamma/stack/header/RNSStackHeaderIconMapper.mm
new file mode 100644
index 0000000000..9b7035b094
--- /dev/null
+++ b/ios/gamma/stack/header/RNSStackHeaderIconMapper.mm
@@ -0,0 +1,52 @@
+#import "RNSStackHeaderIconMapper.h"
+
+@implementation RNSStackHeaderIconMapper
+
++ (nullable RNSStackHeaderIconData *)iconFromDictionary:(nullable id)dictionary
+{
+  if (![dictionary isKindOfClass:[NSDictionary class]]) {
+    return nil;
+  }
+  NSDictionary *dict = (NSDictionary *)dictionary;
+
+  NSString *type = dict[@"type"];
+  if (![type isKindOfClass:[NSString class]]) {
+    return nil;
+  }
+
+  if ([type isEqualToString:@"sfSymbol"]) {
+    return [[RNSStackHeaderIconData alloc] initWithType:RNSStackHeaderIconTypeSfSymbol
+                                           resourceName:dict[@"name"]
+                                             jsonSource:nil];
+  }
+
+  if ([type isEqualToString:@"xcasset"]) {
+    return [[RNSStackHeaderIconData alloc] initWithType:RNSStackHeaderIconTypeXcasset
+                                           resourceName:dict[@"name"]
+                                             jsonSource:nil];
+  }
+
+  if ([type isEqualToString:@"imageSource"]) {
+    NSDictionary *source = dict[@"imageSource"];
+    if (![source isKindOfClass:[NSDictionary class]]) {
+      return nil;
+    }
+    return [[RNSStackHeaderIconData alloc] initWithType:RNSStackHeaderIconTypeImageSource
+                                           resourceName:nil
+                                             jsonSource:source];
+  }
+
+  if ([type isEqualToString:@"templateSource"]) {
+    NSDictionary *source = dict[@"templateSource"];
+    if (![source isKindOfClass:[NSDictionary class]]) {
+      return nil;
+    }
+    return [[RNSStackHeaderIconData alloc] initWithType:RNSStackHeaderIconTypeTemplateSource
+                                           resourceName:nil
+                                             jsonSource:source];
+  }
+
+  return nil;
+}
+
+@end
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconResolver.h b/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
new file mode 100644
index 0000000000..6412acb55b
--- /dev/null
+++ b/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
@@ -0,0 +1,25 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+#import "RNSImageLoading.h"
+#import "RNSStackHeaderIconData.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface RNSStackHeaderIconResolver : NSObject
+
+/**
+ Resolves an icon synchronously if possible, otherwise starts an async load.
+
+ @return UIImage if resolved synchronously, nil if async load was started.
+ For async loads, the completion block is called on the main queue with the loaded image,
+ and iconData.resolvedImage is set automatically.
+ */
++ (nullable UIImage *)resolveIcon:(RNSStackHeaderIconData *)iconData
+                  withImageLoader:(id<RNSImageLoading>)imageLoader
+             asyncCompletionBlock:(nullable void (^)(UIImage *_Nullable))completionBlock;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm b/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
new file mode 100644
index 0000000000..6377f0e0a2
--- /dev/null
+++ b/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
@@ -0,0 +1,50 @@
+#import "RNSStackHeaderIconResolver.h"
+
+@implementation RNSStackHeaderIconResolver
+
++ (nullable UIImage *)resolveIcon:(RNSStackHeaderIconData *)iconData
+                  withImageLoader:(id<RNSImageLoading>)imageLoader
+             asyncCompletionBlock:(nullable void (^)(UIImage *_Nullable))completionBlock
+{
+  if (iconData == nil) {
+    return nil;
+  }
+
+  // If we already resolved this icon, return cached image
+  if (iconData.resolvedImage != nil) {
+    return iconData.resolvedImage;
+  }
+
+  switch (iconData.iconType) {
+    case RNSStackHeaderIconTypeSfSymbol: {
+      UIImage *image = [UIImage systemImageNamed:iconData.resourceName];
+      iconData.resolvedImage = image;
+      return image;
+    }
+    case RNSStackHeaderIconTypeXcasset: {
+      UIImage *image = [UIImage imageNamed:iconData.resourceName];
+      iconData.resolvedImage = image;
+      return image;
+    }
+    case RNSStackHeaderIconTypeImageSource:
+    case RNSStackHeaderIconTypeTemplateSource: {
+      if (imageLoader == nil || iconData.jsonSource == nil) {
+        return nil;
+      }
+      // Weak ref to iconData to avoid retaining it if the item is removed before load completes
+      __weak RNSStackHeaderIconData *weakIconData = iconData;
+      [imageLoader loadImageFromJsonSource:iconData.jsonSource
+                                asTemplate:iconData.iconType == RNSStackHeaderIconTypeTemplateSource
+                    withCompletionCallback:^(UIImage *_Nullable image) {
+                      weakIconData.resolvedImage = image;
+                      if (completionBlock) {
+                        completionBlock(image);
+                      }
+                    }];
+      // Completion may have already fired synchronously if image was cached
+      return iconData.resolvedImage;
+    }
+  }
+}
+
+@end
diff --git a/ios/gamma/stack/header/RNSStackHeaderItemComponentView.h b/ios/gamma/stack/header/RNSStackHeaderItemComponentView.h
index 99669af789..686c4f67a7 100644
--- a/ios/gamma/stack/header/RNSStackHeaderItemComponentView.h
+++ b/ios/gamma/stack/header/RNSStackHeaderItemComponentView.h
@@ -13,6 +13,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, readonly) RNSHeaderItemPlacement placement;
 @property (nonatomic, readonly, nullable) NSString *itemId;
 @property (nonatomic, readonly, nullable) NSString *title;
+@property (nonatomic, readonly, nullable) RNSStackHeaderIconData *icon;
 @property (nonatomic, readonly, nullable) RNSStackHeaderMenuData *menu;
 @property (nonatomic, readonly, nullable) UIView *customView;
 @property (nonatomic, readonly) BOOL respondsToOnPress;
diff --git a/ios/gamma/stack/header/RNSStackHeaderItemComponentView.mm b/ios/gamma/stack/header/RNSStackHeaderItemComponentView.mm
index 5fe09cbe15..e75e2851de 100644
--- a/ios/gamma/stack/header/RNSStackHeaderItemComponentView.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderItemComponentView.mm
@@ -2,6 +2,7 @@
 #import "RNSConversions-Stack.h"
 #import "RNSConversions.h"
 #import "RNSDefines.h"
+#import "RNSStackHeaderIconMapper.h"
 #import "RNSStackHeaderItemEventEmitter.h"
 #import "RNSStackHeaderItemShadowStateProxy.h"
 #import "RNSStackHeaderMenuData.h"
@@ -44,6 +45,7 @@ - (void)resetProps
 {
   _itemId = nil;
   _title = nil;
+  _icon = nil;
   _menu = nil;
   _placement = RNSHeaderItemPlacementTrailing;
   _didSetHeaderItemPlacement = NO;
@@ -164,6 +166,12 @@ - (void)updateProps:(const react::Props::Shared &)props oldProps:(const react::P
     needsUpdate = YES;
   }
 
+  if (oldItemProps.icon != newItemProps.icon) {
+    _icon = [RNSStackHeaderIconMapper
+        iconFromDictionary:rnscreens::conversion::RNSConvertFollyDynamicToId(newItemProps.icon)];
+    needsUpdate = YES;
+  }
+
   if (oldItemProps.menu != newItemProps.menu) {
     _menu = [RNSStackHeaderMenuMapper
         menuFromDictionary:rnscreens::conversion::RNSConvertFollyDynamicToId(newItemProps.menu)];
diff --git a/ios/gamma/stack/header/RNSStackHeaderItemDataProviding.h b/ios/gamma/stack/header/RNSStackHeaderItemDataProviding.h
index 44b4fa620e..37e7f70ecf 100644
--- a/ios/gamma/stack/header/RNSStackHeaderItemDataProviding.h
+++ b/ios/gamma/stack/header/RNSStackHeaderItemDataProviding.h
@@ -3,6 +3,7 @@
 #import <UIKit/UIKit.h>
 
 #import "RNSHeaderItemPlacement.h"
+#import "RNSStackHeaderIconData.h"
 #import "RNSStackHeaderMenuData.h"
 
 NS_ASSUME_NONNULL_BEGIN
@@ -12,6 +13,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, readonly) RNSHeaderItemPlacement placement;
 @property (nonatomic, readonly, nullable) NSString *itemId;
 @property (nonatomic, readonly, nullable) NSString *title;
+@property (nonatomic, readonly, nullable) RNSStackHeaderIconData *icon;
 @property (nonatomic, readonly, nullable) RNSStackHeaderMenuData *menu;
 @property (nonatomic, readonly, nullable) UIView *customView;
 @property (nonatomic, readonly) BOOL respondsToOnPress;
diff --git a/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.h b/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.h
index 0993e4b13c..2105f30461 100644
--- a/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.h
+++ b/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.h
@@ -1,6 +1,8 @@
 #pragma once
 
 #import <UIKit/UIKit.h>
+
+#import "RNSImageLoading.h"
 #import "RNSStackHeaderEventsDelegate.h"
 #import "RNSStackHeaderMenuData.h"
 #import "RNSStackHeaderMenuToggleStateTracker.h"
@@ -11,16 +13,17 @@ NS_ASSUME_NONNULL_BEGIN
 
 /**
  Applies menu specification to the item. Sets up event delegate to receive
- menu updates when user selects options or clicks actions.
- Since menu needs to be rebuilt after user changes selection,
- the `menuToggleCallback` is triggered and the caller is expected
+ menu updates when user selects options or clicks actions. Since menu needs
+ to be rebuilt after user changes selection or after async icon load,
+ the `menuInvalidatedCallback` is triggered and the caller is expected
  to reapply the menu there.
  */
 + (void)applyMenu:(RNSStackHeaderMenuData *)data
              toBarButtonItem:(UIBarButtonItem *)item
     withHeaderEventsDelegate:(id<RNSStackHeaderEventsDelegate>)delegate
                 stateTracker:(RNSStackHeaderMenuToggleStateTracker *)tracker
-          menuToggleCallback:(nullable void (^)(void))onMenuToggle;
+             withImageLoader:(id<RNSImageLoading>)imageLoader
+     menuInvalidatedCallback:(nullable void (^)(void))onMenuInvalidated;
 
 @end
 
diff --git a/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm b/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm
index 2ec97fc283..fe1821af5b 100644
--- a/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm
@@ -1,5 +1,6 @@
 #import "RNSStackHeaderMenuCoordinator.h"
 #import "RNSDefines.h"
+#import "RNSStackHeaderIconResolver.h"
 
 #import <React/RCTAssert.h>
 
@@ -9,7 +10,8 @@ + (void)applyMenu:(RNSStackHeaderMenuData *)data
              toBarButtonItem:(UIBarButtonItem *)item
     withHeaderEventsDelegate:(id<RNSStackHeaderEventsDelegate>)delegate
                 stateTracker:(RNSStackHeaderMenuToggleStateTracker *)tracker
-          menuToggleCallback:(nullable void (^)(void))onMenuToggle
+             withImageLoader:(id<RNSImageLoading>)imageLoader
+     menuInvalidatedCallback:(nullable void (^)(void))onMenuInvalidated
 {
 #if !TARGET_OS_TV || __TV_OS_VERSION_MAX_ALLOWED >= 170000
   if (@available(tvOS 17.0, *)) {
@@ -18,7 +20,8 @@ + (void)applyMenu:(RNSStackHeaderMenuData *)data
                               stateTracker:tracker
                        singleSelectionRoot:nil
         initialSingleSelectionStateClaimed:NULL
-                        menuToggleCallback:onMenuToggle];
+                           withImageLoader:imageLoader
+                   menuInvalidatedCallback:onMenuInvalidated];
   }
 #endif // !TARGET_OS_TV || __TV_OS_VERSION_MAX_ALLOWED >= 170000
 }
@@ -28,7 +31,8 @@ + (UIMenu *)buildMenuFromData:(RNSStackHeaderMenuData *)data
                           stateTracker:(RNSStackHeaderMenuToggleStateTracker *)tracker
                    singleSelectionRoot:(nullable RNSStackHeaderMenuData *)singleSelectionRoot
     initialSingleSelectionStateClaimed:(BOOL *)initialSingleSelectionStateClaimed
-                    menuToggleCallback:(nullable void (^)(void))onMenuToggle
+                       withImageLoader:(id<RNSImageLoading>)imageLoader
+               menuInvalidatedCallback:(nullable void (^)(void))onMenuInvalidated
 {
   // Resolve singleSelection root: first menu in hierarchy with singleSelection becomes the root.
   // Only the root is set the singleSelection option - less things to check if sth goes wrong
@@ -52,13 +56,25 @@ + (UIMenu *)buildMenuFromData:(RNSStackHeaderMenuData *)data
                                              parentMenu:data
                                     singleSelectionRoot:resolvedRoot
                      initialSingleSelectionStateClaimed:initialSingleSelectionStateClaimed
-                                     menuToggleCallback:onMenuToggle];
+                                        withImageLoader:imageLoader
+                                menuInvalidatedCallback:onMenuInvalidated];
     if (element != nil) {
       [elements addObject:element];
     }
   }
 
-  return [UIMenu menuWithTitle:data.title image:nil identifier:nil options:options children:elements];
+  UIImage *menuImage = nil;
+  if (data.icon != nil) {
+    menuImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
+                                        withImageLoader:imageLoader
+                                   asyncCompletionBlock:^(UIImage *_Nullable image) {
+                                     if (onMenuInvalidated) {
+                                       onMenuInvalidated();
+                                     }
+                                   }];
+  }
+
+  return [UIMenu menuWithTitle:data.title image:menuImage identifier:nil options:options children:elements];
 }
 
 + (nullable UIMenuElement *)buildElementFromData:(id<RNSStackHeaderMenuElement>)element
@@ -67,7 +83,8 @@ + (nullable UIMenuElement *)buildElementFromData:(id<RNSStackHeaderMenuElement>)
                                       parentMenu:(RNSStackHeaderMenuData *)parentMenu
                              singleSelectionRoot:(nullable RNSStackHeaderMenuData *)singleSelectionRoot
               initialSingleSelectionStateClaimed:(BOOL *)initialSingleSelectionStateClaimed
-                              menuToggleCallback:(nullable void (^)(void))onMenuToggle
+                                 withImageLoader:(id<RNSImageLoading>)imageLoader
+                         menuInvalidatedCallback:(nullable void (^)(void))onMenuInvalidated
 {
   if ([element isKindOfClass:[RNSStackHeaderMenuData class]]) {
     return [self buildMenuFromData:(RNSStackHeaderMenuData *)element
@@ -75,7 +92,8 @@ + (nullable UIMenuElement *)buildElementFromData:(id<RNSStackHeaderMenuElement>)
                               stateTracker:tracker
                        singleSelectionRoot:singleSelectionRoot
         initialSingleSelectionStateClaimed:initialSingleSelectionStateClaimed
-                        menuToggleCallback:onMenuToggle];
+                           withImageLoader:imageLoader
+                   menuInvalidatedCallback:onMenuInvalidated];
   }
 
   if ([element isKindOfClass:[RNSStackHeaderMenuItemData class]]) {
@@ -101,11 +119,15 @@ + (nullable UIMenuElement *)buildElementFromData:(id<RNSStackHeaderMenuElement>)
                    singleSelectionRoot:singleSelectionRoot
                     toggleStateTracker:tracker
                   headerEventsDelegate:delegate
-                    menuToggleCallback:onMenuToggle];
+                       withImageLoader:imageLoader
+               menuInvalidatedCallback:onMenuInvalidated];
     }
 
     // it effective type is not 'toggle', then it is a regular action button that triggers onPress instead
-    return [self buildActionFromData:itemData withHeaderEventsDelegate:delegate];
+    return [self buildActionFromData:itemData
+            withHeaderEventsDelegate:delegate
+                     withImageLoader:imageLoader
+             menuInvalidatedCallback:onMenuInvalidated];
   }
 
   return nil;
@@ -126,7 +148,8 @@ + (nullable UIMenuElement *)buildToggleFromData:(RNSStackHeaderMenuItemData *)da
                             singleSelectionRoot:(nullable RNSStackHeaderMenuData *)singleSelectionRoot
                              toggleStateTracker:(RNSStackHeaderMenuToggleStateTracker *)tracker
                            headerEventsDelegate:(id<RNSStackHeaderEventsDelegate>)delegate
-                             menuToggleCallback:(nullable void (^)(void))onMenuToggle
+                                withImageLoader:(id<RNSImageLoading>)imageLoader
+                        menuInvalidatedCallback:(nullable void (^)(void))onMenuInvalidated
 {
   BOOL isItemToggledOn = [tracker getToggleStateForItemWithId:data.menuElementId initialState:data.initialToggleState];
   BOOL insideSingleSelection = singleSelectionRoot != nil;
@@ -135,9 +158,20 @@ + (nullable UIMenuElement *)buildToggleFromData:(RNSStackHeaderMenuItemData *)da
 
   __weak id<RNSStackHeaderEventsDelegate> weakDelegate = delegate;
 
+  UIImage *iconImage = nil;
+  if (data.icon != nil) {
+    iconImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
+                                        withImageLoader:imageLoader
+                                   asyncCompletionBlock:^(UIImage *_Nullable image) {
+                                     if (onMenuInvalidated) {
+                                       onMenuInvalidated();
+                                     }
+                                   }];
+  }
+
   UIAction *toggleAction = [UIAction
       actionWithTitle:data.title
-                image:nil
+                image:iconImage
            identifier:nil
               handler:^(__kindof UIAction *_Nonnull action) {
                 NSArray<NSString *> *toggleItemsIds = insideSingleSelection
@@ -164,8 +198,8 @@ + (nullable UIMenuElement *)buildToggleFromData:(RNSStackHeaderMenuItemData *)da
                   [tracker setToggleStateChanged:NO];
                 }
 
-                if (onMenuToggle) {
-                  onMenuToggle();
+                if (onMenuInvalidated) {
+                  onMenuInvalidated();
                 }
               }];
   toggleAction.state = isItemToggledOn ? UIMenuElementStateOn : UIMenuElementStateOff;
@@ -177,11 +211,24 @@ + (nullable UIMenuElement *)buildToggleFromData:(RNSStackHeaderMenuItemData *)da
 
 + (nullable UIMenuElement *)buildActionFromData:(RNSStackHeaderMenuItemData *)data
                        withHeaderEventsDelegate:(id<RNSStackHeaderEventsDelegate>)delegate
+                                withImageLoader:(id<RNSImageLoading>)imageLoader
+                        menuInvalidatedCallback:(nullable void (^)(void))onMenuInvalidated
 {
   __weak id<RNSStackHeaderEventsDelegate> weakDelegate = delegate;
 
+  UIImage *iconImage = nil;
+  if (data.icon != nil) {
+    iconImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
+                                        withImageLoader:imageLoader
+                                   asyncCompletionBlock:^(UIImage *_Nullable image) {
+                                     if (onMenuInvalidated) {
+                                       onMenuInvalidated();
+                                     }
+                                   }];
+  }
+
   UIAction *action = [UIAction actionWithTitle:data.title
-                                         image:nil
+                                         image:iconImage
                                     identifier:nil
                                        handler:^(__kindof UIAction *_Nonnull action) {
                                          [weakDelegate didPressMenuItem:data.menuElementId];
diff --git a/ios/gamma/stack/header/RNSStackHeaderMenuData.h b/ios/gamma/stack/header/RNSStackHeaderMenuData.h
index 90c1dcc93e..6734600b81 100644
--- a/ios/gamma/stack/header/RNSStackHeaderMenuData.h
+++ b/ios/gamma/stack/header/RNSStackHeaderMenuData.h
@@ -2,6 +2,8 @@
 
 #import <Foundation/Foundation.h>
 
+@class RNSStackHeaderIconData;
+
 NS_ASSUME_NONNULL_BEGIN
 
 typedef NS_ENUM(NSInteger, RNSMenuItemType) {
@@ -22,12 +24,14 @@ typedef NS_ENUM(NSInteger, RNSMenuItemType) {
 @property (nonatomic, readonly) RNSMenuItemType itemType;
 @property (nonatomic, readonly) BOOL initialToggleState;
 @property (nonatomic, readonly) BOOL keepsMenuPresented;
+@property (nonatomic, strong, readonly, nullable) RNSStackHeaderIconData *icon;
 
 - (instancetype)initWithId:(NSString *)menuElementId
                      title:(nullable NSString *)title
                   itemType:(RNSMenuItemType)itemType
         initialToggleState:(BOOL)initialToggleState
-        keepsMenuPresented:(BOOL)keepsMenuPresented;
+        keepsMenuPresented:(BOOL)keepsMenuPresented
+                      icon:(nullable RNSStackHeaderIconData *)icon;
 
 @end
 
@@ -36,11 +40,13 @@ typedef NS_ENUM(NSInteger, RNSMenuItemType) {
 @property (nonatomic, copy, readonly, nullable) NSString *title;
 @property (nonatomic, readonly) BOOL singleSelection;
 @property (nonatomic, copy, readonly) NSArray<id<RNSStackHeaderMenuElement>> *children;
+@property (nonatomic, strong, readonly, nullable) RNSStackHeaderIconData *icon;
 
 - (instancetype)initWithId:(NSString *)menuElementId
                      title:(nullable NSString *)title
            singleSelection:(BOOL)singleSelection
-                  children:(NSArray<id<RNSStackHeaderMenuElement>> *)children;
+                  children:(NSArray<id<RNSStackHeaderMenuElement>> *)children
+                      icon:(nullable RNSStackHeaderIconData *)icon;
 
 @end
 
diff --git a/ios/gamma/stack/header/RNSStackHeaderMenuData.mm b/ios/gamma/stack/header/RNSStackHeaderMenuData.mm
index dc1a6cf1cd..4d00bc1512 100644
--- a/ios/gamma/stack/header/RNSStackHeaderMenuData.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderMenuData.mm
@@ -9,6 +9,7 @@ - (instancetype)initWithId:(NSString *)menuElementId
                   itemType:(RNSMenuItemType)itemType
         initialToggleState:(BOOL)initialToggleState
         keepsMenuPresented:(BOOL)keepsMenuPresented
+                      icon:(nullable RNSStackHeaderIconData *)icon
 {
   if (self = [super init]) {
     _menuElementId = [menuElementId copy];
@@ -16,6 +17,7 @@ - (instancetype)initWithId:(NSString *)menuElementId
     _itemType = itemType;
     _initialToggleState = initialToggleState;
     _keepsMenuPresented = keepsMenuPresented;
+    _icon = icon;
   }
   return self;
 }
@@ -30,12 +32,14 @@ - (instancetype)initWithId:(NSString *)menuElementId
                      title:(nullable NSString *)title
            singleSelection:(BOOL)singleSelection
                   children:(NSArray<id<RNSStackHeaderMenuElement>> *)children
+                      icon:(nullable RNSStackHeaderIconData *)icon
 {
   if (self = [super init]) {
     _menuElementId = [menuElementId copy];
     _title = [title copy];
     _singleSelection = singleSelection;
     _children = [children copy];
+    _icon = icon;
   }
   return self;
 }
diff --git a/ios/gamma/stack/header/RNSStackHeaderMenuMapper.mm b/ios/gamma/stack/header/RNSStackHeaderMenuMapper.mm
index d62749dad0..7df2c57459 100644
--- a/ios/gamma/stack/header/RNSStackHeaderMenuMapper.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderMenuMapper.mm
@@ -1,12 +1,13 @@
 #import "RNSStackHeaderMenuMapper.h"
+#import "RNSStackHeaderIconMapper.h"
 
 #import <React/RCTAssert.h>
 #import <React/RCTLog.h>
 
 static NSSet<NSString *> *const kRNSAllowedMenuKeys =
-    [NSSet setWithObjects:@"id", @"type", @"title", @"children", @"singleSelection", nil];
-static NSSet<NSString *> *const kRNSAllowedMenuItemKeys =
-    [NSSet setWithObjects:@"id", @"type", @"title", @"itemType", @"initialToggleState", @"keepsMenuPresented", nil];
+    [NSSet setWithObjects:@"id", @"type", @"title", @"children", @"singleSelection", @"icon", nil];
+static NSSet<NSString *> *const kRNSAllowedMenuItemKeys = [NSSet
+    setWithObjects:@"id", @"type", @"title", @"itemType", @"initialToggleState", @"keepsMenuPresented", @"icon", nil];
 
 @implementation RNSStackHeaderMenuMapper
 
@@ -36,10 +37,13 @@ + (nullable RNSStackHeaderMenuData *)menuFromDictionary:(nullable id)dictionary
 
   BOOL singleSelection = [self boolForKey:@"singleSelection" in:dict];
 
+  RNSStackHeaderIconData *icon = [RNSStackHeaderIconMapper iconFromDictionary:dict[@"icon"]];
+
   return [[RNSStackHeaderMenuData alloc] initWithId:[self stringForKey:@"id" in:dict]
                                               title:[self stringForKey:@"title" in:dict]
                                     singleSelection:singleSelection
-                                           children:children];
+                                           children:children
+                                               icon:icon];
 }
 
 + (nullable id<RNSStackHeaderMenuElement>)elementFromDictionary:(nullable id)dictionary
@@ -55,12 +59,15 @@ + (nullable RNSStackHeaderMenuData *)menuFromDictionary:(nullable id)dictionary
   } else if ([type isEqual:@"menuItem"]) {
     [RNSStackHeaderMenuMapper validateMenuItemKeys:dict];
 
+    RNSStackHeaderIconData *icon = [RNSStackHeaderIconMapper iconFromDictionary:dict[@"icon"]];
+
     return [[RNSStackHeaderMenuItemData alloc] initWithId:[self stringForKey:@"id" in:dict]
                                                     title:[self stringForKey:@"title" in:dict]
                                                  itemType:[self itemTypeFromString:[self stringForKey:@"itemType"
                                                                                                    in:dict]]
                                        initialToggleState:[self boolForKey:@"initialToggleState" in:dict]
-                                       keepsMenuPresented:[self boolForKey:@"keepsMenuPresented" in:dict]];
+                                       keepsMenuPresented:[self boolForKey:@"keepsMenuPresented" in:dict]
+                                                     icon:icon];
   }
 
   return nil;
diff --git a/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.h b/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.h
index cb89c1c8ea..19e3fe175a 100644
--- a/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.h
+++ b/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.h
@@ -1,6 +1,7 @@
 #pragma once
 
 #import <UIKit/UIKit.h>
+#import "RNSImageLoading.h"
 #import "RNSStackHeaderConfigDataProviding.h"
 #import "RNSStackHeaderEventsDelegate.h"
 #import "RNSViewFrameChangeDelegate.h"
@@ -16,6 +17,7 @@ NS_ASSUME_NONNULL_BEGIN
 @property (nonatomic, weak, nullable) id<RNSStackHeaderConfigDataProviding> configDataProvider;
 @property (nonatomic, weak, nullable) id<RNSViewFrameChangeDelegate> frameChangeDelegate;
 @property (nonatomic, weak, nullable) id<RNSStackHeaderEventsDelegate> eventsDelegate;
+@property (nonatomic, weak, nullable) id<RNSImageLoading> imageLoader;
 
 - (void)rebuild;
 
diff --git a/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm b/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm
index a1b60108e4..9f6fe1cc27 100644
--- a/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm
+++ b/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm
@@ -269,9 +269,10 @@ - (void)reapplyMenuForItemWithId:(NSString *)itemId
                            toBarButtonItem:barButtonItem
                   withHeaderEventsDelegate:_eventsDelegate
                               stateTracker:tracker
-                        menuToggleCallback:^{
-                          [weakSelf reapplyMenuForItemWithId:itemId];
-                        }];
+                           withImageLoader:_imageLoader
+                   menuInvalidatedCallback:^{
+                     [weakSelf reapplyMenuForItemWithId:itemId];
+                   }];
 }
 
 - (nullable id<RNSStackHeaderItemDataProviding>)findItemWithId:(NSString *)itemId
@@ -366,7 +367,8 @@ - (UIBarButtonItem *)buildBarButtonItemForItem:(id<RNSStackHeaderItemDataProvidi
 {
   UIBarButtonItem *barButtonItem = [RNSStackHeaderContentFactory barButtonItemForHeaderItem:item
                                                                     withFrameChangeDelegate:_frameChangeDelegate
-                                                                   withHeaderEventsDelegate:_eventsDelegate];
+                                                                   withHeaderEventsDelegate:_eventsDelegate
+                                                                            withImageLoader:_imageLoader];
 
   if (item.menu != nil && item.itemId != nil) {
     RNSStackHeaderMenuToggleStateTracker *tracker = [_trackerRegistry trackerForItemId:item.itemId];
@@ -376,9 +378,10 @@ - (UIBarButtonItem *)buildBarButtonItemForItem:(id<RNSStackHeaderItemDataProvidi
                              toBarButtonItem:barButtonItem
                     withHeaderEventsDelegate:_eventsDelegate
                                 stateTracker:tracker
-                          menuToggleCallback:^{
-                            [weakSelf reapplyMenuForItemWithId:capturedItemId];
-                          }];
+                             withImageLoader:_imageLoader
+                     menuInvalidatedCallback:^{
+                       [weakSelf reapplyMenuForItemWithId:capturedItemId];
+                     }];
   }
 
   if (item.itemId != nil) {
diff --git a/ios/helpers/image/RNSImageLoading.h b/ios/helpers/image/RNSImageLoading.h
new file mode 100644
index 0000000000..6dc1451d61
--- /dev/null
+++ b/ios/helpers/image/RNSImageLoading.h
@@ -0,0 +1,15 @@
+#pragma once
+
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol RNSImageLoading <NSObject>
+
+- (void)loadImageFromJsonSource:(NSDictionary *)jsonSource
+                     asTemplate:(BOOL)isTemplate
+         withCompletionCallback:(void (^)(UIImage *image))completionBlock;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/src/components/gamma/stack/header/StackHeaderConfig.ios.types.ts b/src/components/gamma/stack/header/StackHeaderConfig.ios.types.ts
index 2dd161879a..368494da49 100644
--- a/src/components/gamma/stack/header/StackHeaderConfig.ios.types.ts
+++ b/src/components/gamma/stack/header/StackHeaderConfig.ios.types.ts
@@ -1,4 +1,5 @@
 import type { ReactElement } from 'react';
+import type { PlatformIconIOS } from '../../../../types';
 import type { StackHeaderMenuIOS } from './ios/StackHeaderMenu.ios.types';
 
 export interface StackHeaderBaseItemIOS {
@@ -14,6 +15,17 @@ export interface StackHeaderBaseItemIOS {
    * @platform iOS
    */
   title?: string | undefined;
+  /**
+   * @summary Icon displayed for the header item.
+   *
+   * @description
+   * Supports SF Symbols, xcassets, and image sources. For async image sources,
+   * the item renders without an icon first and updates when loaded.
+   * Ignored when custom view ({@link StackHeaderInlineCustomItemIOS.render | render}) is set.
+   *
+   * @platform iOS
+   */
+  icon?: PlatformIconIOS | undefined;
 }
 
 export interface SupportsMenuIOS {
diff --git a/src/components/gamma/stack/header/index.ts b/src/components/gamma/stack/header/index.ts
index 554d1996cb..565a111dad 100644
--- a/src/components/gamma/stack/header/index.ts
+++ b/src/components/gamma/stack/header/index.ts
@@ -6,3 +6,5 @@ export type * from './StackHeaderConfig.android.types';
 export type * from './StackHeaderConfig.ios.types';
 
 export type * from './ios/StackHeaderMenu.ios.types';
+
+export type { PlatformIconIOS } from '../../../../types';
diff --git a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
index 2758c32a96..919755fbd6 100644
--- a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
+++ b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
@@ -1,11 +1,58 @@
-import React, { useCallback } from 'react';
+import React, { useCallback, useMemo } from 'react';
 import StackHeaderItemIOSNativeComponent from '../../../../../fabric/gamma/stack/StackHeaderItemIOSNativeComponent';
 import type { HeaderItemPressEvent } from '../../../../../fabric/gamma/stack/StackHeaderItemIOSNativeComponent';
 import type { StackHeaderItemProps } from './StackHeaderItem.ios.types';
-import { NativeSyntheticEvent, StyleSheet } from 'react-native';
+import type { PlatformIconIOS } from '../../../../../types';
+import type {
+  StackHeaderMenuIOS,
+  StackHeaderMenuElementIOS,
+} from './StackHeaderMenu.ios.types';
+import { Image, NativeSyntheticEvent, StyleSheet } from 'react-native';
+
+function resolveIconAssetSources(
+  icon: PlatformIconIOS | undefined,
+): PlatformIconIOS | undefined {
+  if (icon == null) {
+    return undefined;
+  }
+  if (icon.type === 'imageSource') {
+    return {
+      type: 'imageSource',
+      imageSource: Image.resolveAssetSource(icon.imageSource),
+    };
+  }
+  if (icon.type === 'templateSource') {
+    return {
+      type: 'templateSource',
+      templateSource: Image.resolveAssetSource(icon.templateSource),
+    };
+  }
+  return icon;
+}
+
+function resolveMenuElementIcons(
+  element: StackHeaderMenuElementIOS,
+): StackHeaderMenuElementIOS {
+  if (element.type === 'menuItem') {
+    if (element.icon == null) {
+      return element;
+    }
+    return { ...element, icon: resolveIconAssetSources(element.icon) };
+  }
+  return resolveMenuIcons(element);
+}
+
+function resolveMenuIcons(menu: StackHeaderMenuIOS): StackHeaderMenuIOS {
+  const resolvedIcon = resolveIconAssetSources(menu.icon);
+  const resolvedChildren = menu.children.map(resolveMenuElementIcons);
+  if (resolvedIcon === menu.icon && resolvedChildren === menu.children) {
+    return menu;
+  }
+  return { ...menu, icon: resolvedIcon, children: resolvedChildren };
+}
 
 export default function StackHeaderItem(props: StackHeaderItemProps) {
-  const { render, onPress, ...rest } = props;
+  const { render, onPress, icon, menu, ...rest } = props;
 
   // `rest.menu` includes some JS callback within nested menu specification
   // codegen strips JS functions and replaces them with NULLT and keys of such type
@@ -18,9 +65,17 @@ export default function StackHeaderItem(props: StackHeaderItemProps) {
     [onPress],
   );
 
+  const resolvedIcon = useMemo(() => resolveIconAssetSources(icon), [icon]);
+  const resolvedMenu = useMemo(
+    () => (menu != null ? resolveMenuIcons(menu) : undefined),
+    [menu],
+  );
+
   return (
     <StackHeaderItemIOSNativeComponent
       {...rest}
+      icon={resolvedIcon}
+      menu={resolvedMenu}
       // We need to tell iOS that we want the handler to be attached only when we actually require it
       // because doing so makes the menu appear on long press instead of tap
       respondsToOnPress={!!onPress}
diff --git a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.types.ts b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.types.ts
index 01af6dad08..9458dc4df9 100644
--- a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.types.ts
+++ b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.types.ts
@@ -1,4 +1,5 @@
 import type { ReactElement } from 'react';
+import type { PlatformIconIOS } from '../../../../../types';
 import type { StackHeaderMenuIOS } from './StackHeaderMenu.ios.types';
 
 export type StackHeaderItemPlacement =
@@ -12,6 +13,7 @@ export type StackHeaderItemProps = {
   placement: StackHeaderItemPlacement;
   itemId?: string | undefined;
   title?: string | undefined;
+  icon?: PlatformIconIOS | undefined;
   render?: (() => ReactElement) | undefined;
   menu?: StackHeaderMenuIOS | undefined;
   onPress?: (() => void) | undefined;
diff --git a/src/components/gamma/stack/header/ios/StackHeaderMenu.ios.types.ts b/src/components/gamma/stack/header/ios/StackHeaderMenu.ios.types.ts
index 537b198c7d..bf4b7c3513 100644
--- a/src/components/gamma/stack/header/ios/StackHeaderMenu.ios.types.ts
+++ b/src/components/gamma/stack/header/ios/StackHeaderMenu.ios.types.ts
@@ -8,6 +8,8 @@
  *
  * @platform ios
  */
+import type { PlatformIconIOS } from '../../../../../types';
+
 export interface StackHeaderMenuItemIOS {
   /**
    * @summary Unique identifier of the menu item.
@@ -63,6 +65,16 @@ export interface StackHeaderMenuItemIOS {
    * @platform ios
    */
   initialToggleState?: boolean | undefined;
+  /**
+   * @summary Icon displayed for the menu item.
+   *
+   * @description
+   * Supports SF Symbols, xcassets, and image sources. For async image sources,
+   * the menu item renders without an icon first and updates when loaded.
+   *
+   * @platform ios
+   */
+  icon?: PlatformIconIOS | undefined;
   /**
    * @summary Callback invoked when the menu item is pressed.
    *
@@ -149,6 +161,16 @@ export interface StackHeaderMenuIOS {
    * @platform ios
    */
   singleSelection?: boolean | undefined;
+  /**
+   * @summary Icon displayed for the submenu.
+   *
+   * @description
+   * Supports SF Symbols, xcassets, and image sources. For async image sources,
+   * the menu renders without an icon first and updates when loaded.
+   *
+   * @platform ios
+   */
+  icon?: PlatformIconIOS | undefined;
   /**
    * @summary Child elements of this menu.
    *
diff --git a/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts b/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
index ae4a6d63ee..b00279a53e 100644
--- a/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
+++ b/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
@@ -32,10 +32,15 @@ export type StackHeaderMenuElementIOS =
 // eslint-disable-next-line @typescript-eslint/ban-types
 export type HeaderItemPressEvent = Readonly<{}>;
 
+export type PlatformIconIOS = {
+  type: string;
+};
+
 export interface NativeProps extends ViewProps {
   placement?: CT.WithDefault<Placement, 'trailing'>;
   itemId?: string | undefined;
   title?: string | undefined;
+  icon?: UnsafeMixed<PlatformIconIOS> | undefined;
   menu?: UnsafeMixed<StackHeaderMenuIOS> | undefined;
   respondsToOnPress?: CT.WithDefault<boolean, false>;
   onHeaderItemPress?: CT.DirectEventHandler<HeaderItemPressEvent> | undefined;

From ecc114127f89b237de2a81460c7ce84b08c49890 Mon Sep 17 00:00:00 2001
From: Konrad Michalik <konrad.michalik@swmansion.com>
Date: Mon, 6 Jul 2026 16:37:16 +0200
Subject: [PATCH 2/6] Add scenario.md

---
 .../test-stack-header-icon-ios/scenario.md    | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md

diff --git a/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md
new file mode 100644
index 0000000000..72eeac66a8
--- /dev/null
+++ b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md
@@ -0,0 +1,39 @@
+# Test Scenario: Stack Header Icons (iOS)
+
+## Details
+
+**Description:** This test focuses on handling icons and images in header with runtime updates.
+
+**OS test creation version:** iOS 26.4, iPadOS 26.4
+
+## E2E test
+
+TBD
+
+## Prerequisites
+
+- iOS / iPadOS emulator
+
+## Note (Optional)
+
+- Crossfade doesn't work when changing between async images.
+- Changing items in menu while it is presented (default for this test) results in visible layout shifts.
+This is native behavior, we can't do much here
+
+## Steps on iPhone
+
+1. Inspect the header right item
+  - [ ] A "star" sfSymbol is visible
+2. Repeatedly click on "Cycle item icon"
+  - [ ] First, "star" changes to filled "3"
+  - [ ] Second, filled "3" changes to search icon
+  - [ ] Third, search icon changes to "3"
+  - [ ] Lastly, "3" changes again to "star"
+3. Inspect the menu
+  - [ ] Long press on the header item shows the menu
+  - [ ] both menu items and submenu items have "star" visible on the left side
+4. Repeatedly click on "Cycle icons" action inside the menu
+  - [ ] First, "star" changes to filled "3"
+  - [ ] Second, filled "3" changes to search icon
+  - [ ] Third, search icon changes to "3"
+  - [ ] Lastly, "3" changes again to "star"

From b342d0a835a41227d0eb540add1b679e301f078d Mon Sep 17 00:00:00 2001
From: Konrad Michalik <konrad.michalik@swmansion.com>
Date: Mon, 6 Jul 2026 16:58:34 +0200
Subject: [PATCH 3/6] fix copilot issues

---
 .../header/RNSStackHeaderConfigComponentView.mm    | 14 +++++++++++---
 ios/helpers/image/RNSImageLoading.h                |  2 +-
 .../gamma/stack/header/ios/StackHeaderItem.ios.tsx |  3 ---
 .../stack/StackHeaderItemIOSNativeComponent.ts     |  1 +
 4 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
index 0b2ba63cb0..476f443750 100644
--- a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
@@ -69,12 +69,20 @@ - (void)resetProps
 
 - (void)loadImageFromJsonSource:(NSDictionary *)jsonSource
                      asTemplate:(BOOL)isTemplate
-         withCompletionCallback:(void (^)(UIImage *image))completionBlock
+         withCompletionCallback:(void (^)(UIImage *_Nullable image))completionBlock
 {
-  RCTAssert(_imageLoader != nil, @"[RNScreens] imageLoader must not be nil when loading images");
+  if (_imageLoader == nil) {
+    RNSLog(@"[RNScreens] imageLoader must not be nil when loading images");
+    completionBlock(nil);
+    return;
+  }
 
   RCTImageSource *imageSource = [RCTConvert RCTImageSource:jsonSource];
-  RCTAssert(imageSource != nil, @"[RNScreens] Expected nonnil image source");
+  if (imageSource == nil) {
+    RNSLog(@"[RNScreens] Expected nonnil image source");
+    completionBlock(nil);
+    return;
+  }
 
   [RNSImageLoadingHelper loadImageFromSource:imageSource
                              withImageLoader:_imageLoader
diff --git a/ios/helpers/image/RNSImageLoading.h b/ios/helpers/image/RNSImageLoading.h
index 6dc1451d61..2c8235ef54 100644
--- a/ios/helpers/image/RNSImageLoading.h
+++ b/ios/helpers/image/RNSImageLoading.h
@@ -8,7 +8,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (void)loadImageFromJsonSource:(NSDictionary *)jsonSource
                      asTemplate:(BOOL)isTemplate
-         withCompletionCallback:(void (^)(UIImage *image))completionBlock;
+         withCompletionCallback:(void (^)(UIImage *_Nullable image))completionBlock;
 
 @end
 
diff --git a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
index 919755fbd6..41a46d33e2 100644
--- a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
+++ b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
@@ -45,9 +45,6 @@ function resolveMenuElementIcons(
 function resolveMenuIcons(menu: StackHeaderMenuIOS): StackHeaderMenuIOS {
   const resolvedIcon = resolveIconAssetSources(menu.icon);
   const resolvedChildren = menu.children.map(resolveMenuElementIcons);
-  if (resolvedIcon === menu.icon && resolvedChildren === menu.children) {
-    return menu;
-  }
   return { ...menu, icon: resolvedIcon, children: resolvedChildren };
 }
 
diff --git a/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts b/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
index b00279a53e..400c5740cc 100644
--- a/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
+++ b/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
@@ -34,6 +34,7 @@ export type HeaderItemPressEvent = Readonly<{}>;
 
 export type PlatformIconIOS = {
   type: string;
+  /* there are multiple variants, we're skipping them here */
 };
 
 export interface NativeProps extends ViewProps {

From 4404e7ad7c725a70b25c47126436a142b83eec09 Mon Sep 17 00:00:00 2001
From: Konrad Michalik <konrad.michalik@swmansion.com>
Date: Mon, 6 Jul 2026 17:12:30 +0200
Subject: [PATCH 4/6] remove comment

---
 ios/gamma/stack/header/RNSStackHeaderIconResolver.mm | 1 -
 1 file changed, 1 deletion(-)

diff --git a/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm b/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
index 6377f0e0a2..74f819f4e7 100644
--- a/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
@@ -41,7 +41,6 @@ + (nullable UIImage *)resolveIcon:(RNSStackHeaderIconData *)iconData
                         completionBlock(image);
                       }
                     }];
-      // Completion may have already fired synchronously if image was cached
       return iconData.resolvedImage;
     }
   }

From 5014e9106f5066945e079e7999fd27d0715b1a71 Mon Sep 17 00:00:00 2001
From: Konrad Michalik <konrad.michalik@swmansion.com>
Date: Thu, 9 Jul 2026 12:45:24 +0200
Subject: [PATCH 5/6] apply CR suggestions

---
 .../test-stack-header-icon-ios/index.tsx      |  8 ++---
 .../test-stack-header-icon-ios/scenario.md    |  2 +-
 .../RNSStackHeaderConfigComponentView.mm      | 11 ++++---
 .../header/RNSStackHeaderContentFactory.mm    |  4 +--
 .../stack/header/RNSStackHeaderIconResolver.h | 10 +++---
 .../screen/RNSStackScreenHeaderCoordinator.mm | 12 +++----
 src/components/gamma/stack/header/index.ts    |  2 --
 .../stack/header/ios/StackHeaderItem.ios.tsx  |  7 ++--
 .../StackHeaderItemIOSNativeComponent.ts      | 33 ++++++++++++++++---
 9 files changed, 57 insertions(+), 32 deletions(-)

diff --git a/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx
index cc513f90fa..cb64850bdb 100644
--- a/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx
+++ b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/index.tsx
@@ -4,14 +4,12 @@ import {
   StackContainer,
   useStackNavigationContext,
 } from '@apps/shared/gamma/containers/stack';
-import {
-  StackHeaderConfigProps,
-  PlatformIconIOS,
-} from 'react-native-screens/components/gamma/stack/header';
+import { StackHeaderConfigProps } from 'react-native-screens/components/gamma/stack/header';
 import { Button, ScrollView, Text, View, StyleSheet } from 'react-native';
 import { scenarioDescription } from './scenario-description';
 import { ToastProvider, useToast } from '@apps/shared';
 import { Colors } from '@apps/shared/styling';
+import { type PlatformIconIOS } from 'react-native-screens';
 
 type IconVariant = 'sfSymbol' | 'xcasset' | 'imageSource' | 'templateSource';
 
@@ -200,7 +198,7 @@ function ConfigScreen() {
       </View>
       <View style={styles.section}>
         <Button
-          title="Push screen with same config"
+          title="Push another screen"
           onPress={() => navigation.push('Home')}
         />
       </View>
diff --git a/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md
index 72eeac66a8..a180538e1f 100644
--- a/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md
+++ b/apps/src/tests/single-feature-tests/stack-v5/test-stack-header-icon-ios/scenario.md
@@ -12,7 +12,7 @@ TBD
 
 ## Prerequisites
 
-- iOS / iPadOS emulator
+- iOS / iPadOS simulator
 
 ## Note (Optional)
 
diff --git a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
index 476f443750..4f164a2c4a 100644
--- a/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderConfigComponentView.mm
@@ -1,6 +1,5 @@
 #import "RNSStackHeaderConfigComponentView.h"
 #import "RNSImageLoadingHelper.h"
-#import "RNSLog.h"
 #import "RNSStackHeaderConfigEventEmitter.h"
 #import "RNSStackHeaderConfigShadowStateProxy.h"
 #import "RNSStackHeaderItemComponentView.h"
@@ -11,7 +10,9 @@
 #import "RNSStackScreenHeaderCoordinator.h"
 
 #import <React/RCTConversions.h>
+#import <React/RCTConvert.h>
 #import <React/RCTImageLoader.h>
+#import <React/RCTLog.h>
 #import <react/renderer/components/rnscreens/Props.h>
 #import <react/renderer/components/rnscreens/RCTComponentViewHelpers.h>
 #import <react/utils/ManagedObjectWrapper.h>
@@ -72,14 +73,14 @@ - (void)loadImageFromJsonSource:(NSDictionary *)jsonSource
          withCompletionCallback:(void (^)(UIImage *_Nullable image))completionBlock
 {
   if (_imageLoader == nil) {
-    RNSLog(@"[RNScreens] imageLoader must not be nil when loading images");
+    RCTLogError(@"[RNScreens] imageLoader must not be nil when loading images");
     completionBlock(nil);
     return;
   }
 
   RCTImageSource *imageSource = [RCTConvert RCTImageSource:jsonSource];
   if (imageSource == nil) {
-    RNSLog(@"[RNScreens] Expected nonnil image source");
+    RCTLogError(@"[RNScreens] Expected nonnil image source");
     completionBlock(nil);
     return;
   }
@@ -167,7 +168,7 @@ - (void)unmountChildComponentView:(UIView<RCTComponentViewProtocol> *)childCompo
 - (void)headerItemDidInvalidateWithId:(NSString *)itemId
 {
   if (itemId == nil) {
-    RNSLog(@"[RNScreens] headerItemDidInvalidateWithId called with nil id, will run full header rebuild");
+    RCTLogWarn(@"[RNScreens] headerItemDidInvalidateWithId called with nil id, will run full header rebuild");
     [[self headerCoordinator] rebuild];
     return;
   }
@@ -177,7 +178,7 @@ - (void)headerItemDidInvalidateWithId:(NSString *)itemId
 - (void)headerItemMenuDidChangeWithId:(NSString *)itemId
 {
   if (itemId == nil) {
-    RNSLog(@"[RNScreens] headerItemMenuDidChangeWithId called with nil id, will run full header rebuild");
+    RCTLogWarn(@"[RNScreens] headerItemMenuDidChangeWithId called with nil id, will run full header rebuild");
     [[self headerCoordinator] rebuild];
     return;
   }
diff --git a/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm b/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
index 1c67494792..921da79346 100644
--- a/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
@@ -1,6 +1,6 @@
 #import "RNSStackHeaderContentFactory.h"
+#import <React/RCTLog.h>
 #import "RNSDefines.h"
-#import "RNSLog.h"
 #import "RNSStackHeaderIconResolver.h"
 #import "RNSStackHeaderItemWrapperView.h"
 #import "RNSStackHeaderMenuCoordinator.h"
@@ -57,7 +57,7 @@ + (UIBarButtonItem *)labelBarButtonItemForHeaderItem:(id<RNSStackHeaderItemDataP
                                                  withImageLoader:imageLoader
                                             asyncCompletionBlock:^(UIImage *_Nullable image) {
                                               if (weakBarButtonItem == nil) {
-                                                RNSLog(@"[RNScreens] Attempt to set image on nil UIBarButtonItem");
+                                                RCTLogWarn(@"[RNScreens] Attempt to set image on nil UIBarButtonItem");
                                                 return;
                                               }
                                               weakBarButtonItem.image = image;
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconResolver.h b/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
index 6412acb55b..7ec05b8038 100644
--- a/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
+++ b/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
@@ -10,11 +10,11 @@ NS_ASSUME_NONNULL_BEGIN
 @interface RNSStackHeaderIconResolver : NSObject
 
 /**
- Resolves an icon synchronously if possible, otherwise starts an async load.
-
- @return UIImage if resolved synchronously, nil if async load was started.
- For async loads, the completion block is called on the main queue with the loaded image,
- and iconData.resolvedImage is set automatically.
+ * Resolves an icon synchronously if possible, otherwise starts an async load.
+ *
+ * @return UIImage if resolved synchronously, nil if async load was started.
+ * For async loads, the completion block is called on the main queue with the loaded image,
+ * and iconData.resolvedImage is set automatically.
  */
 + (nullable UIImage *)resolveIcon:(RNSStackHeaderIconData *)iconData
                   withImageLoader:(id<RNSImageLoading>)imageLoader
diff --git a/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm b/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm
index 9f6fe1cc27..a0fe845c6a 100644
--- a/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm
+++ b/ios/gamma/stack/screen/RNSStackScreenHeaderCoordinator.mm
@@ -1,7 +1,6 @@
 #import "RNSStackScreenHeaderCoordinator.h"
 #import "RCTAssert.h"
 #import "RNSDefines.h"
-#import "RNSLog.h"
 #import "RNSStackHeaderContentFactory.h"
 #import "RNSStackHeaderItemDataProviding.h"
 #import "RNSStackHeaderItemSpacerDataProviding.h"
@@ -10,6 +9,7 @@
 #import "RNSStackNavigationBarCoordinator.h"
 #import "RNSStackNavigationController.h"
 #import "RNSStackScreenController.h"
+#import "React/RCTLog.h"
 
 @implementation RNSStackScreenHeaderCoordinator {
   __weak RNSStackScreenController *_Nullable _screenController;
@@ -84,13 +84,13 @@ - (void)rebuild
       }
     } else if ([child conformsToProtocol:@protocol(RNSStackHeaderItemSpacerDataProviding)]) {
       id<RNSStackHeaderItemSpacerDataProviding> spacer = (id<RNSStackHeaderItemSpacerDataProviding>)child;
-      UIBarButtonItem *bbi = [RNSStackHeaderContentFactory spacerForHeaderSpacerItem:spacer];
+      UIBarButtonItem *barButtonItem = [RNSStackHeaderContentFactory spacerForHeaderSpacerItem:spacer];
       switch (spacer.placement) {
         case RNSHeaderItemSpacerPlacementLeading:
-          [_leadingBarButtonItems addObject:bbi];
+          [_leadingBarButtonItems addObject:barButtonItem];
           break;
         case RNSHeaderItemSpacerPlacementTrailing:
-          [_trailingBarButtonItems addObject:bbi];
+          [_trailingBarButtonItems addObject:barButtonItem];
           break;
       }
     }
@@ -142,7 +142,7 @@ - (void)rebuildItemWithId:(NSString *)itemId
         if (index != NSNotFound) {
           _leadingBarButtonItems[index] = newBarButtonItem;
         } else {
-          RNSLog(@"[RNScreens] Item %@ not found for rebuild.", oldBarButtonItem);
+          RCTLogWarn(@"[RNScreens] Item %@ not found for rebuild.", oldBarButtonItem);
         }
       }
 
@@ -157,7 +157,7 @@ - (void)rebuildItemWithId:(NSString *)itemId
         if (index != NSNotFound) {
           _trailingBarButtonItems[index] = newBarButtonItem;
         } else {
-          RNSLog(@"[RNScreens] Item %@ not found for rebuild.", oldBarButtonItem);
+          RCTLogWarn(@"[RNScreens] Item %@ not found for rebuild.", oldBarButtonItem);
         }
       }
 
diff --git a/src/components/gamma/stack/header/index.ts b/src/components/gamma/stack/header/index.ts
index 565a111dad..554d1996cb 100644
--- a/src/components/gamma/stack/header/index.ts
+++ b/src/components/gamma/stack/header/index.ts
@@ -6,5 +6,3 @@ export type * from './StackHeaderConfig.android.types';
 export type * from './StackHeaderConfig.ios.types';
 
 export type * from './ios/StackHeaderMenu.ios.types';
-
-export type { PlatformIconIOS } from '../../../../types';
diff --git a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
index 41a46d33e2..5c9586125f 100644
--- a/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
+++ b/src/components/gamma/stack/header/ios/StackHeaderItem.ios.tsx
@@ -1,6 +1,9 @@
 import React, { useCallback, useMemo } from 'react';
 import StackHeaderItemIOSNativeComponent from '../../../../../fabric/gamma/stack/StackHeaderItemIOSNativeComponent';
-import type { HeaderItemPressEvent } from '../../../../../fabric/gamma/stack/StackHeaderItemIOSNativeComponent';
+import type {
+  HeaderItemPressEvent,
+  PlatformIconIOS as ResolvedPlatformIconIOS,
+} from '../../../../../fabric/gamma/stack/StackHeaderItemIOSNativeComponent';
 import type { StackHeaderItemProps } from './StackHeaderItem.ios.types';
 import type { PlatformIconIOS } from '../../../../../types';
 import type {
@@ -11,7 +14,7 @@ import { Image, NativeSyntheticEvent, StyleSheet } from 'react-native';
 
 function resolveIconAssetSources(
   icon: PlatformIconIOS | undefined,
-): PlatformIconIOS | undefined {
+): ResolvedPlatformIconIOS | undefined {
   if (icon == null) {
     return undefined;
   }
diff --git a/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts b/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
index 400c5740cc..8277271de8 100644
--- a/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
+++ b/src/fabric/gamma/stack/StackHeaderItemIOSNativeComponent.ts
@@ -1,6 +1,10 @@
 'use client';
 
-import type { CodegenTypes as CT, ViewProps } from 'react-native';
+import type {
+  CodegenTypes as CT,
+  ImageResolvedAssetSource,
+  ViewProps,
+} from 'react-native';
 import { codegenNativeComponent } from 'react-native';
 import { UnsafeMixed } from '../../codegenUtils';
 
@@ -32,11 +36,32 @@ export type StackHeaderMenuElementIOS =
 // eslint-disable-next-line @typescript-eslint/ban-types
 export type HeaderItemPressEvent = Readonly<{}>;
 
-export type PlatformIconIOS = {
-  type: string;
-  /* there are multiple variants, we're skipping them here */
+export type PlatformIconShared = {
+  type: 'imageSource';
+  imageSource: ImageResolvedAssetSource;
 };
 
+export type PlatformIconTemplateIOS = {
+  type: 'templateSource';
+  templateSource: ImageResolvedAssetSource;
+};
+
+export type PlatformIconIOSSfSymbol = {
+  type: 'sfSymbol';
+  name: string;
+};
+
+export type PlatformIconIOSXcasset = {
+  type: 'xcasset';
+  name: string;
+};
+
+export type PlatformIconIOS =
+  | PlatformIconIOSSfSymbol
+  | PlatformIconIOSXcasset
+  | PlatformIconTemplateIOS
+  | PlatformIconShared;
+
 export interface NativeProps extends ViewProps {
   placement?: CT.WithDefault<Placement, 'trailing'>;
   itemId?: string | undefined;

From ba953103433118d2de951543d8de54b9e40a922c Mon Sep 17 00:00:00 2001
From: Konrad Michalik <63911178+kmichalikk@users.noreply.github.com>
Date: Fri, 10 Jul 2026 08:17:00 +0200
Subject: [PATCH 6/6] feat(Stack v5, iOS): Add sizing to placeholder image for
 async load (#4295)

## Description

This PR adds sizing calculations for placeholder image size so that
placeholders for images that are loaded asynchronously are not causing
layout shifts.

## Changes

- added a method `RNSStackHeaderIconResolver.placeholderImageForIcon`
that builds an empty image of target image's size and used for item and
menu rendering

## Before & after - visual documentation

| Before | After |
| --- | --- |
| <video
src="https://github.com/user-attachments/assets/b3b401ea-d22c-4063-9383-a1deda1b0b02"
/> | <video
src="https://github.com/user-attachments/assets/0cedf8dd-021f-4afe-a3e3-82c69e96568c"
/> |
| <video
src="https://github.com/user-attachments/assets/3d4cd395-95ae-4656-894c-abe812fa8572"
/> | <video
src="https://github.com/user-attachments/assets/58836fbc-b737-486e-8dd5-d003ddc11981"
/> |

## Test plan

Use test-stack-header-item-ios SFT

## 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
---
 .../header/RNSStackHeaderContentFactory.mm    |  2 +-
 .../stack/header/RNSStackHeaderIconResolver.h |  6 +++
 .../header/RNSStackHeaderIconResolver.mm      | 18 ++++++++
 .../header/RNSStackHeaderMenuCoordinator.mm   | 45 ++++++++++---------
 4 files changed, 49 insertions(+), 22 deletions(-)

diff --git a/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm b/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
index 921da79346..90bb9a7077 100644
--- a/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderContentFactory.mm
@@ -62,7 +62,7 @@ + (UIBarButtonItem *)labelBarButtonItemForHeaderItem:(id<RNSStackHeaderItemDataP
                                               }
                                               weakBarButtonItem.image = image;
                                             }];
-    barButtonItem.image = syncImage ? syncImage : [UIImage imageWithCIImage:[CIImage emptyImage]];
+    barButtonItem.image = syncImage ? syncImage : [RNSStackHeaderIconResolver placeholderImageForIcon:item.icon];
   }
 
   return barButtonItem;
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconResolver.h b/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
index 7ec05b8038..32e7c6bfb9 100644
--- a/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
+++ b/ios/gamma/stack/header/RNSStackHeaderIconResolver.h
@@ -20,6 +20,12 @@ NS_ASSUME_NONNULL_BEGIN
                   withImageLoader:(id<RNSImageLoading>)imageLoader
              asyncCompletionBlock:(nullable void (^)(UIImage *_Nullable))completionBlock;
 
+/**
+ Creates a transparent placeholder image matching the size declared in iconData's jsonSource.
+ Falls back to 1x1 if size info is missing and returns nil if jsonSource is nil (sfSymbols, xcassets).
+ */
++ (nullable UIImage *)placeholderImageForIcon:(RNSStackHeaderIconData *)iconData;
+
 @end
 
 NS_ASSUME_NONNULL_END
diff --git a/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm b/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
index 74f819f4e7..b84d1f82ec 100644
--- a/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderIconResolver.mm
@@ -46,4 +46,22 @@ + (nullable UIImage *)resolveIcon:(RNSStackHeaderIconData *)iconData
   }
 }
 
++ (nullable UIImage *)placeholderImageForIcon:(RNSStackHeaderIconData *)iconData
+{
+  if (iconData.jsonSource == nil) {
+    return nil;
+  }
+
+  CGFloat width = [iconData.jsonSource[@"width"] doubleValue];
+  CGFloat height = [iconData.jsonSource[@"height"] doubleValue];
+  CGFloat scale = [iconData.jsonSource[@"scale"] doubleValue] ?: 1.0;
+  CGSize size = (width > 0 && height > 0) ? CGSizeMake(width, height) : CGSizeMake(1, 1);
+
+  UIGraphicsImageRendererFormat *format = [UIGraphicsImageRendererFormat defaultFormat];
+  format.scale = scale;
+  UIGraphicsImageRenderer *renderer = [[UIGraphicsImageRenderer alloc] initWithSize:size format:format];
+  return [renderer imageWithActions:^(UIGraphicsImageRendererContext *_Nonnull ctx){
+  }];
+}
+
 @end
diff --git a/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm b/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm
index fe1821af5b..73edc82f14 100644
--- a/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm
+++ b/ios/gamma/stack/header/RNSStackHeaderMenuCoordinator.mm
@@ -65,13 +65,14 @@ + (UIMenu *)buildMenuFromData:(RNSStackHeaderMenuData *)data
 
   UIImage *menuImage = nil;
   if (data.icon != nil) {
-    menuImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
-                                        withImageLoader:imageLoader
-                                   asyncCompletionBlock:^(UIImage *_Nullable image) {
-                                     if (onMenuInvalidated) {
-                                       onMenuInvalidated();
-                                     }
-                                   }];
+    UIImage *syncImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
+                                                 withImageLoader:imageLoader
+                                            asyncCompletionBlock:^(UIImage *_Nullable image) {
+                                              if (onMenuInvalidated) {
+                                                onMenuInvalidated();
+                                              }
+                                            }];
+    menuImage = syncImage ? syncImage : [RNSStackHeaderIconResolver placeholderImageForIcon:data.icon];
   }
 
   return [UIMenu menuWithTitle:data.title image:menuImage identifier:nil options:options children:elements];
@@ -160,13 +161,14 @@ + (nullable UIMenuElement *)buildToggleFromData:(RNSStackHeaderMenuItemData *)da
 
   UIImage *iconImage = nil;
   if (data.icon != nil) {
-    iconImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
-                                        withImageLoader:imageLoader
-                                   asyncCompletionBlock:^(UIImage *_Nullable image) {
-                                     if (onMenuInvalidated) {
-                                       onMenuInvalidated();
-                                     }
-                                   }];
+    UIImage *syncImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
+                                                 withImageLoader:imageLoader
+                                            asyncCompletionBlock:^(UIImage *_Nullable image) {
+                                              if (onMenuInvalidated) {
+                                                onMenuInvalidated();
+                                              }
+                                            }];
+    iconImage = syncImage ? syncImage : [RNSStackHeaderIconResolver placeholderImageForIcon:data.icon];
   }
 
   UIAction *toggleAction = [UIAction
@@ -218,13 +220,14 @@ + (nullable UIMenuElement *)buildActionFromData:(RNSStackHeaderMenuItemData *)da
 
   UIImage *iconImage = nil;
   if (data.icon != nil) {
-    iconImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
-                                        withImageLoader:imageLoader
-                                   asyncCompletionBlock:^(UIImage *_Nullable image) {
-                                     if (onMenuInvalidated) {
-                                       onMenuInvalidated();
-                                     }
-                                   }];
+    UIImage *syncImage = [RNSStackHeaderIconResolver resolveIcon:data.icon
+                                                 withImageLoader:imageLoader
+                                            asyncCompletionBlock:^(UIImage *_Nullable image) {
+                                              if (onMenuInvalidated) {
+                                                onMenuInvalidated();
+                                              }
+                                            }];
+    iconImage = syncImage ? syncImage : [RNSStackHeaderIconResolver placeholderImageForIcon:data.icon];
   }
 
   UIAction *action = [UIAction actionWithTitle:data.title