|
| 1 | +--- |
| 2 | +id: icons |
| 3 | +title: Icons |
| 4 | +sidebar_label: Using Icons |
| 5 | +--- |
| 6 | + |
| 7 | +Many components in React Navigation accept icons to customize their appearance. Depending on the component and platform, different types of icons are supported. |
| 8 | + |
| 9 | +Here are some common places where icons are used in React Navigation: |
| 10 | + |
| 11 | +- [`tabBarIcon`](bottom-tab-navigator.md#tabbaricon) option in Bottom Tab Navigator |
| 12 | +- [`headerBackIcon`](native-stack-navigator.md#headerbackicon) option in Native Stack Navigator |
| 13 | +- [`headerBackIcon`](stack-navigator.md#headerbackicon) option in Stack Navigator |
| 14 | +- [`backIcon`](elements.md#headerbackbutton) prop in `HeaderBackButton` component |
| 15 | + |
| 16 | +There are 2 types of icons supported natively: |
| 17 | + |
| 18 | +## SF Symbols |
| 19 | + |
| 20 | +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. |
| 21 | + |
| 22 | +Options such as `tabBarIcon` and `headerBackIcon` accept an object with `type: 'sfSymbol'` and a `name` property to specify the SF Symbol to use: |
| 23 | + |
| 24 | +```js |
| 25 | +tabBarIcon: { |
| 26 | + type: 'sfSymbol', |
| 27 | + name: 'star.fill', |
| 28 | +} |
| 29 | +``` |
| 30 | + |
| 31 | +In addition, React Navigation also exports a `SFSymbol` component that you can use to render SF Symbols directly in your own components: |
| 32 | + |
| 33 | +```js |
| 34 | +import { SFSymbol } from '@react-navigation/native'; |
| 35 | + |
| 36 | +function MyComponent() { |
| 37 | + return <SFSymbol name="star.fill" size={24} />; |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +The component accepts the following props: |
| 42 | + |
| 43 | +- `name` |
| 44 | + |
| 45 | + The name of the SF Symbol to display (required). |
| 46 | + |
| 47 | + The SF Symbol icons have multiple variants for the same icon. Different variants can be used by adding a suffix to the name. For example, `star`, `star.fill`, and `star.circle` are all variants of the star symbol. |
| 48 | + |
| 49 | + You can browse the available symbols and their variants in the [SF Symbols app](https://developer.apple.com/sf-symbols/). |
| 50 | + |
| 51 | +- `size` |
| 52 | + |
| 53 | + The size of the symbol. Defaults to `24`. |
| 54 | + |
| 55 | +- `color` |
| 56 | + |
| 57 | + The color of the symbol. |
| 58 | + |
| 59 | +- `weight` |
| 60 | + |
| 61 | + The weight of the symbol. Can be one of: |
| 62 | + - `'thin'` (`100`) |
| 63 | + - `'ultralight'` (`200`) |
| 64 | + - `'light'` (`300`) |
| 65 | + - `'regular'` (`400`) |
| 66 | + - `'medium'` (`500`) |
| 67 | + - `'semibold'` (`600`) |
| 68 | + - `'bold'` (`700`) |
| 69 | + - `'extrabold'` (`800`) |
| 70 | + - `'black'` (`900`) |
| 71 | + |
| 72 | +- `scale` |
| 73 | + |
| 74 | + The scale of the symbol relative to the font size. Can be one of: |
| 75 | + - `'small'` |
| 76 | + - `'medium'` |
| 77 | + - `'large'` |
| 78 | + |
| 79 | +- `mode` |
| 80 | + |
| 81 | + The rendering mode of the symbol. Can be one of: |
| 82 | + - `'monochrome'` (single color tint, default) |
| 83 | + - `'hierarchical'` (derived hierarchy from a single color) |
| 84 | + - `'palette'` (explicit colors for each layer) |
| 85 | + - `'multicolor'` (symbol's built-in multicolor scheme) |
| 86 | + |
| 87 | +- `colors` |
| 88 | + |
| 89 | + Object of colors to use for `hierarchical` and `palette` modes. It can have the following properties: |
| 90 | + - `primary` (base color for `hierarchical` mode) |
| 91 | + - `secondary` (second layer in `palette` mode) |
| 92 | + - `tertiary` (third layer in `palette` mode). |
| 93 | + |
| 94 | + Example: |
| 95 | + |
| 96 | + ```js |
| 97 | + <SFSymbol |
| 98 | + name="star.fill" |
| 99 | + size={30} |
| 100 | + mode="palette" |
| 101 | + colors={{ |
| 102 | + primary: 'red', |
| 103 | + secondary: 'yellow', |
| 104 | + tertiary: 'blue', |
| 105 | + }} |
| 106 | + /> |
| 107 | + ``` |
| 108 | + |
| 109 | + If the prop is not provided, the primary color defaults to the `color` prop. |
| 110 | + |
| 111 | +- `animation` |
| 112 | + |
| 113 | + The animation effect to apply when the symbol changes. Requires iOS 17+. Ignored on earlier versions. |
| 114 | + |
| 115 | + It can be a string with the following values: |
| 116 | + - `'bounce'` |
| 117 | + - `'pulse'` |
| 118 | + - `'appear'` |
| 119 | + - `'disappear'` |
| 120 | + - `'variableColor'` |
| 121 | + - `'breathe'` |
| 122 | + - `'wiggle'` |
| 123 | + - `'rotate'` |
| 124 | + |
| 125 | + Or a custom animation object with the following properties: |
| 126 | + - `effect`: The animation effect to apply (such as `'bounce'`, `'pulse'`, etc.). |
| 127 | + - `repeating`: Whether the animation repeats continuously. Defaults to `false`. |
| 128 | + - `repeatCount`: Number of times to repeat the animation. Ignored if `repeating` is `true`. |
| 129 | + - `speed`: Speed multiplier for the animation. Defaults to `1`. |
| 130 | + - `wholeSymbol`: Whether to animate the whole symbol at once or layer by layer. Defaults to `false`. |
| 131 | + - `direction`: Direction of the animation. Applicable to `bounce` and `wiggle`. |
| 132 | + - `reversing`: Whether the variable color effect reverses with each cycle. Only applicable to `variableColor`. Defaults to `false`. |
| 133 | + - `cumulative`: Whether each layer remains changed until the end of the cycle. Only applicable to `variableColor`. Defaults to `false`. |
| 134 | + |
| 135 | +## Material Symbols |
| 136 | + |
| 137 | +Material Symbols is a library of over 2,500 glyphs designed to integrate well with Material Design on Android. |
| 138 | + |
| 139 | +Unlike SF Symbols, Material Symbols are not included on Android. So React Navigation includes copies of the Material Symbols fonts to render the icons. By default, it uses the `"outlined"` variant with `400` weight. |
| 140 | + |
| 141 | +You can customize which variant and weights are included in the bundle by setting a `"react-navigation"` key in your app's `package.json`: |
| 142 | + |
| 143 | +```json |
| 144 | +"react-navigation": { |
| 145 | + "material-symbols": { |
| 146 | + "fonts": [ |
| 147 | + { |
| 148 | + "variant": "rounded", |
| 149 | + "weights": [300] |
| 150 | + } |
| 151 | + ] |
| 152 | + } |
| 153 | +} |
| 154 | +``` |
| 155 | + |
| 156 | +This will include the `"rounded"` variant with `300` weight in the bundle. |
| 157 | + |
| 158 | +If you don't use Material Symbols and want to reduce your app size, you can also disable the font entirely by specifying an empty array for `fonts`: |
| 159 | + |
| 160 | +```json |
| 161 | +"react-navigation": { |
| 162 | + "material-symbols": { |
| 163 | + "fonts": [] |
| 164 | + } |
| 165 | +} |
| 166 | +``` |
| 167 | + |
| 168 | +:::info |
| 169 | + |
| 170 | +You'll need to rebuild your app after changing the font configuration in `package.json`. |
| 171 | + |
| 172 | +::: |
| 173 | + |
| 174 | +Options such as `tabBarIcon` and `headerBackIcon` accept an object with `type: 'materialSymbol'` and a `name` property to specify the Material Symbol to use: |
| 175 | + |
| 176 | +```js |
| 177 | +tabBarIcon: { |
| 178 | + type: 'materialSymbol', |
| 179 | + name: 'star', |
| 180 | +} |
| 181 | +``` |
| 182 | + |
| 183 | +The behavior differs depending on the weights and variants included in the bundle. If there is a single variant and weight included, it will be used by default. You don't need to specify the variant or weight in the icon object. |
| 184 | + |
| 185 | +If there are multiple variants or weights included, you can specify the `variant` and `weight` properties in the icon object to choose which one to use: |
| 186 | + |
| 187 | +```js |
| 188 | +tabBarIcon: { |
| 189 | + type: 'materialSymbol', |
| 190 | + name: 'star', |
| 191 | + variant: 'rounded', |
| 192 | + weight: 300, |
| 193 | +} |
| 194 | +``` |
| 195 | + |
| 196 | +In addition, React Navigation also exports a `MaterialSymbol` component that you can use to render Material Symbols directly in your own components: |
| 197 | + |
| 198 | +```js |
| 199 | +import { MaterialSymbol } from '@react-navigation/native'; |
| 200 | + |
| 201 | +function MyComponent() { |
| 202 | + return <MaterialSymbol name="star" size={24} />; |
| 203 | +} |
| 204 | +``` |
| 205 | + |
| 206 | +The component accepts the following props: |
| 207 | + |
| 208 | +- `name` |
| 209 | + |
| 210 | + The name of the Material Symbol to display (required). |
| 211 | + |
| 212 | + You can browse the available symbols in the [Material Symbols website](https://fonts.google.com/icons). |
| 213 | + |
| 214 | +- `size` |
| 215 | + |
| 216 | + The size of the symbol. Defaults to `24`. |
| 217 | + |
| 218 | +- `color` |
| 219 | + |
| 220 | + The color of the symbol. Defaults to black. |
| 221 | + |
| 222 | +- `variant` |
| 223 | + |
| 224 | + The variant of the symbol. Can be one of: |
| 225 | + - `'outlined'` |
| 226 | + - `'rounded'` |
| 227 | + - `'sharp'` |
| 228 | + |
| 229 | + The available variants depend on which variants are included in the bundle. If the specified variant is not included, it will throw an error. |
| 230 | + |
| 231 | +- `weight` |
| 232 | + |
| 233 | + The weight of the symbol. Can be one of: |
| 234 | + - `"thin"` (`100`) |
| 235 | + - `"ultralight"` (`200`) |
| 236 | + - `"light"` (`300`) |
| 237 | + - `"regular"` (`400`) |
| 238 | + - `"medium"` (`500`) |
| 239 | + - `"semibold"` (`600`) |
| 240 | + - `"bold"` (`700`) |
| 241 | + |
| 242 | + The available weights depend on which weights are included in the bundle. If the specified weight is not included, it will throw an error. |
0 commit comments