Update documentation for icons

Author: satya164

versioned_docs/version-7.x/native-stack-navigator.md

@@ -1617,7 +1617,7 @@ If the content's height is less than the sheet's height, the remaining area may
 
 ## Header items
 
-The [`unstable_headerLeftItems`](#unstable_headerleftitems) and [`unstable_headerRightItems`](#unstable_headerrightitems) options allow you to add header items to the left and right side of the header respectively. This items can show native buttons, menus or custom React elements.
+The [`unstable_headerLeftItems`](#unstable_headerleftitems) and [`unstable_headerRightItems`](#unstable_headerrightitems) options allow you to add header items to the left and right side of the header respectively. These items can show native buttons, menus or custom React elements.
 
 On iOS 26+, the header right items can also be collapsed into an overflow menu by the system when there is not enough space to show all items. Note that custom elements (with `type: 'custom'`) won't be collapsed into the overflow menu.
 
@@ -1642,7 +1642,7 @@ Common properties:
   - `color` (of type `ColorValue`)
 - `icon`: Optional icon to show instead of the label.
 
-  The icon can be of following types:
+  The icon can be one of the following types:
   - Local image
 
     ```js
@@ -1657,7 +1657,7 @@ Common properties:
     It also supports [xcasset](https://developer.apple.com/documentation/xcode/adding-images-to-your-xcode-project):
 
     ```js
-    tabBarIcon: {
+    icon: {
       type: 'image',
       source: { uri: 'icon_name' },
     }
@@ -1666,7 +1666,7 @@ Common properties:
     A `tinted` property can be used to control whether the icon should be tinted with the active/inactive color:
 
     ```js
-    tabBarIcon: {
+    icon: {
       type: 'image',
       source: require('./path/to/icon.png'),
       tinted: false,
@@ -1742,14 +1742,7 @@ Supported properties when `type` is `menu`:
       - `type`: Must be `action`.
       - `label`: Label of the menu item.
       - `description`: The secondary text displayed alongside the label of the menu item.
-      - `icon`: Optional icon to show alongside the label. The icon can be a [SF Symbols](https://developer.apple.com/sf-symbols/) name:
-
-        ```js
-        {
-          type: 'sfSymbol',
-          name: 'trash',
-        }
-        ```
+      - `icon`: Optional icon to show alongside the label. It accepts the same formats as `icon` above.
 
       - `onPress`: Function to call when the menu item is pressed.
       - `state`: Optional state of the menu item. Supported values:
@@ -1765,14 +1758,7 @@ Supported properties when `type` is `menu`:
     - `submenu`: An object with the following properties:
       - `type`: Must be `submenu`.
       - `label`: Label of the submenu item.
-      - `icon`: Optional icon to show alongside the label. The icon can be a [SF Symbols](https://developer.apple.com/sf-symbols/) name:
-
-        ```js
-        {
-          type: 'sfSymbol',
-          name: 'pencil',
-        }
-        ```
+      - `icon`: Optional icon to show alongside the label. It accepts the same formats as `icon` above.
 
       - `inline`: Whether the menu is displayed inline with the parent menu. By default, submenus are displayed after expanding the parent menu item. Inline menus are displayed as part of the parent menu as a section. Defaults to `false`.
       - `layout`: How the submenu items are displayed. Supported values:

versioned_docs/version-8.x/bottom-tab-navigator.md

@@ -625,6 +625,14 @@ tabBarIcon: ({ focused }) => {
 
 This not supported on Android with `native` implementation, the icon specified for inactive state will be used for both active and inactive states.
 
+With `custom` implementation, you can also return a React element:
+
+```js
+tabBarIcon: ({ color, size }) => (
+  <MyCustomIcon color={color} size={size} />
+),
+```
+
 To provide different icons for different platforms, you can use [`Platform.select`](https://reactnative.dev/docs/platform-specific-code):
 
 ```js

versioned_docs/version-8.x/drawer-navigator.md

@@ -229,10 +229,12 @@ export default function App() {
 }
 ```
 
+### `DrawerItem`
+
 The `DrawerItem` component accepts the following props:
 
 - `label` (required): The label text of the item. Can be string, or a function returning a react element. e.g. `({ focused, color }) => <Text style={{ color }}>{focused ? 'Focused text' : 'Unfocused text'}</Text>`.
-- `icon`: Icon to display for the item. Accepts a function returning a react element. e.g. `({ focused, color, size }) => <Icon color={color} size={size} name={focused ? 'heart' : 'heart-outline'} />`.
+- `icon`: Icon to display for the item. Accepts an icon object, or a function returning an icon object or a React element. See [Icons](icons.md) for supported icon formats.
 - `focused`: Boolean indicating whether to highlight the drawer item as active.
 - `onPress` (required): Function to execute on press.
 - `activeTintColor`: Color for the icon and label when the item is active.
@@ -300,7 +302,86 @@ String or a function that given `{ focused: boolean, color: string }` returns a
 
 #### `drawerIcon`
 
-Function, that given `{ focused: boolean, color: string, size: number }` returns a React.Node to display in drawer sidebar.
+Icon object to display or a function that given `{ focused: boolean, color: string, size: number }` returns an icon to display in drawer sidebar.
+
+It supports the following types:
+
+- `materialSymbol` (Android only)
+
+  ```js
+  drawerIcon: {
+    type: 'materialSymbol',
+    name: 'favorite',
+  }
+  ```
+
+  It also supports the following optional properties:
+  - `variant` - Supported values: `outlined`, `rounded`, `sharp`
+  - `weight` - Supported values: `100`, `200`, `300`, `400`, `500`, `600`, `700`
+
+  See [Icons](icons.md#material-symbols) for more details.
+
+- `sfSymbol` (iOS only)
+
+  ```js
+  drawerIcon: {
+    type: 'sfSymbol',
+    name: 'heart',
+  }
+  ```
+
+  See [Icons](icons.md#sf-symbols) for more details.
+
+- `image`
+
+  ```js
+  drawerIcon: {
+    type: 'image',
+    source: require('./path/to/icon.png'),
+  }
+  ```
+
+  It also supports [drawable resource](https://developer.android.com/guide/topics/resources/drawable-resource) on Android, [xcasset](https://developer.apple.com/documentation/xcode/adding-images-to-your-xcode-project) on iOS:
+
+  ```js
+  drawerIcon: {
+    type: 'image',
+    source: { uri: 'icon_name' },
+  }
+  ```
+
+  A `tinted` property can be used to control whether the icon should be tinted with the active/inactive color:
+
+  ```js
+  drawerIcon: {
+    type: 'image',
+    source: require('./path/to/icon.png'),
+    tinted: false,
+  }
+  ```
+
+  Set `tinted` to `false` if the image has its own colors that you want to preserve.
+
+  The image is tinted by default.
+
+In addition to the icon object, you can also provide a function which returns an icon object or a React element. It receives `focused`, `color`, and `size` in its argument object:
+
+```js
+drawerIcon: ({ focused }) => {
+  return {
+    type: 'sfSymbol',
+    name: focused ? 'heart.fill' : 'heart',
+  };
+},
+```
+
+To render a custom React element, you can return it from the function:
+
+```js
+drawerIcon: ({ color, size }) => (
+  <MyCustomIcon color={color} size={size} />
+),
+```
 
 #### `drawerActiveTintColor`
 

versioned_docs/version-8.x/elements.md

@@ -668,7 +668,7 @@ A component used to show the back button header. It's the default for [`headerLe
 - `disabled` - Boolean which controls Whether the button is disabled.
 - `onPress` - Callback to call when the button is pressed.
 - `pressColor` - Color for material ripple (Android >= 5.0 only).
-- `backIcon` - Icon to display custom icon in header's back button. See [Custom back icon](#custom-back-icon) section for more details.
+- `icon` - Icon to display custom icon in header's back button. See [Custom back icon](#custom-back-icon) section for more details.
 - `tintColor` - Tint color for the header.
 - `label` - Label text for the button. Usually the title of the previous screen. By default, this is only shown on iOS.
 - `truncatedLabel` - Label text to show when there isn't enough space for the full label.
@@ -694,17 +694,17 @@ Usage:
 
 #### Custom back icon
 
-The `backIcon` prop accepts an icon object for SF Symbols on iOS, Material Symbols on Android and image source on all platforms:
+The `icon` prop accepts an icon object for SF Symbols on iOS, Material Symbols on Android and image source on all platforms:
 
 ```js
 <HeaderBackButton
-  backIcon={Platform.select({
+  icon={Platform.select({
     ios: {
-      type: 'sf-symbol',
+      type: 'sfSymbol',
       name: 'arrow.left',
     },
     android: {
-      type: 'material-symbol',
+      type: 'materialSymbol',
       name: 'arrow_back',
     },
     default: {
@@ -722,7 +722,7 @@ It can also be a function that returns a React Element to render any component:
 
 ```js
 <HeaderBackButton
-  backIcon={({ tintColor }) => (
+  icon={({ tintColor }) => (
     <MyCustomBackIconComponent tintColor={tintColor} />
   )}
   onPress={() => console.log('back pressed')}

versioned_docs/version-8.x/icons.md

@@ -9,10 +9,14 @@ Many components in React Navigation accept icons to customize their appearance.
 Here are some common places where icons are used in React Navigation:
 
 - [`tabBarIcon`](bottom-tab-navigator.md#tabbaricon) option in Bottom Tab Navigator
+- [`tabBarIcon`](material-top-tab-navigator.md#tabbaricon) option in Material Top Tabs Navigator
+- [`drawerIcon`](drawer-navigator.md#drawericon) option in Drawer Navigator
+- [`icon`](drawer-navigator.md#draweritem) prop in `DrawerItem` component
 - [`headerBackIcon`](native-stack-navigator.md#headerbackicon) option in Native Stack Navigator
 - [`headerBackIcon`](stack-navigator.md#headerbackicon) option in Stack Navigator
 - [`icon`](elements.md#headerbackbutton) prop in `HeaderBackButton` component
-- [`icon`](drawer-navigator.md#headerleft) option in `DrawerToggleButton` component
+- [`icon`](drawer-navigator.md#headerleft) prop in `DrawerToggleButton` component
+- [`icon`](native-stack-navigator.md#header-items) property in Native Stack header items (iOS only, `image` and `sfSymbol` only)
 
 Typically, components accept an icon object with a `type` property:
 
@@ -49,7 +53,7 @@ The `sfSymbol` and `materialSymbol` types use the respective system icon librari
 
 SF Symbols is a library of over 6,900 symbols designed to integrate well with the San Francisco system font on Apple platforms. It comes included with iOS and other Apple platforms.
 
-Options such as `tabBarIcon` and `headerBackIcon` accept an object with `type: 'sfSymbol'` and a `name` property to specify the SF Symbol to use:
+Where SF Symbols are supported, icon options and props accept an object with `type: 'sfSymbol'` and a `name` property to specify the SF Symbol to use:
 
 ```js
 tabBarIcon: {
@@ -205,7 +209,7 @@ You'll need to rebuild your app after changing the font configuration in `packag
 
 :::
 
-Options such as `tabBarIcon` and `headerBackIcon` accept an object with `type: 'materialSymbol'` and a `name` property to specify the Material Symbol to use:
+Where Material Symbols are supported, icon options and props accept an object with `type: 'materialSymbol'` and a `name` property to specify the Material Symbol to use:
 
 ```js
 tabBarIcon: {

versioned_docs/version-8.x/material-top-tab-navigator.md

@@ -409,7 +409,86 @@ Whether the tab label should be visible. Defaults to `true`.
 
 #### `tabBarIcon`
 
-Function that given `{ focused: boolean, color: string }` returns a React.Node, to display in the tab bar.
+Icon object to display or a function that given `{ focused: boolean, color: string, size: number }` returns an icon to display in the tab bar.
+
+It supports the following types:
+
+- `materialSymbol` (Android only)
+
+  ```js
+  tabBarIcon: {
+    type: 'materialSymbol',
+    name: 'favorite',
+  }
+  ```
+
+  It also supports the following optional properties:
+  - `variant` - Supported values: `outlined`, `rounded`, `sharp`
+  - `weight` - Supported values: `100`, `200`, `300`, `400`, `500`, `600`, `700`
+
+  See [Icons](icons.md#material-symbols) for more details.
+
+- `sfSymbol` (iOS only)
+
+  ```js
+  tabBarIcon: {
+    type: 'sfSymbol',
+    name: 'heart',
+  }
+  ```
+
+  See [Icons](icons.md#sf-symbols) for more details.
+
+- `image`
+
+  ```js
+  tabBarIcon: {
+    type: 'image',
+    source: require('./path/to/icon.png'),
+  }
+  ```
+
+  It also supports [drawable resource](https://developer.android.com/guide/topics/resources/drawable-resource) on Android, [xcasset](https://developer.apple.com/documentation/xcode/adding-images-to-your-xcode-project) on iOS:
+
+  ```js
+  tabBarIcon: {
+    type: 'image',
+    source: { uri: 'icon_name' },
+  }
+  ```
+
+  A `tinted` property can be used to control whether the icon should be tinted with the active/inactive color:
+
+  ```js
+  tabBarIcon: {
+    type: 'image',
+    source: require('./path/to/icon.png'),
+    tinted: false,
+  }
+  ```
+
+  Set `tinted` to `false` if the image has its own colors that you want to preserve.
+
+  The image is tinted by default.
+
+In addition to the icon object, you can also provide a function which returns an icon object or a React element. It receives `focused`, `color`, and `size` in its argument object:
+
+```js
+tabBarIcon: ({ focused }) => {
+  return {
+    type: 'sfSymbol',
+    name: focused ? 'heart.fill' : 'heart',
+  };
+},
+```
+
+To render a custom React element, you can return it from the function:
+
+```js
+tabBarIcon: ({ color, size }) => (
+  <MyCustomIcon color={color} size={size} />
+),
+```
 
 #### `tabBarShowIcon`