Skip to main content

Icons

ContextMenu supports icons on menu items. Icons are specified by name and resolved differently on each platform. SegmentedControl, Button, ButtonGroup and TextField accept the same names, plus image assets and per-platform sets (the PlatformIcon type); see SegmentedControl Icon Support.

iOS​

Use SF Symbols names. These are built into iOS and require no additional setup.

// Common SF Symbols
image: 'doc.on.doc'; // Copy
image: 'square.and.arrow.up'; // Share
image: 'trash'; // Delete
image: 'pencil'; // Edit
image: 'checkmark.circle'; // Checkmark

Browse available symbols using Apple's SF Symbols app or sfsymbols.com.

Android​

Use drawable resource names from your app's res/drawable directory. You must add these resources yourself.

// Reference drawable by name (without extension)
image: 'content_copy'; // res/drawable/content_copy.xml
image: 'share'; // res/drawable/share.xml
image: 'delete'; // res/drawable/delete.xml

Adding drawable resources:

  1. Create vector drawable XML files in android/app/src/main/res/drawable/
  2. Use Material Icons as a source — download SVG and convert to Android Vector Drawable
  3. Name the file to match the image prop value (e.g., content_copy.xml for image: 'content_copy')

Example vector drawable (res/drawable/content_copy.xml):

<vector xmlns:android="http://schemas.android.com/apk/res/android"
android:width="24dp"
android:height="24dp"
android:viewportWidth="24"
android:viewportHeight="24">
<path
android:fillColor="@android:color/white"
android:pathData="M16,1L4,1c-1.1,0 -2,0.9 -2,2v14h2L4,3h12L16,1zM19,5L8,5c-1.1,0 -2,0.9 -2,2v14c0,1.1 0.9,2 2,2h11c1.1,0 2,-0.9 2,-2L21,7c0,-1.1 -0.9,-2 -2,-2zM19,21L8,21L8,7h11v14z"/>
</vector>

Your own SVG icons​

An icon set that lives as SVG files can reach every native control through one string name, with no mapping table in JS, by adding each icon once per platform under the same name:

  • iOS: open the SVG in Apple's SF Symbols app (File → New Symbol from Template, or drag the SVG into a custom symbol template), export it, and drag the exported .svg into your app's asset catalog as a Symbol Image Set. Symbol names that iOS doesn't ship are looked up in the asset catalog, so 'my.icon' finds a custom symbol named my.icon. Custom symbols scale and weight with the text like the built-in ones. A plain image set (PDF or SVG with "Preserve Vector Data") works too, drawn as a tinted template.
  • Android: import the SVG with Android Studio's Vector Asset Studio (File → New → Vector Asset → Local file), or convert it with a tool such as svg2vectordrawable, into res/drawable/my_icon.xml. Drawable names are the file name, so use a name that is valid on both platforms (lowercase and underscores, my_icon).
<Button label="Deposit" icon="my_icon" />
<TextField trailingIcon="my_icon" />

The library doesn't parse SVG at runtime, and it doesn't bundle Material Symbols: both would add weight and a second rendering path to every app, while the platform formats above are the ones the system renders, tints and scales natively.

Expo​

SF Symbol names work in Expo with no setup. Android drawables are different: with prebuild (Continuous Native Generation), the android/ directory is generated, and drawables added to android/app/src/main/res/drawable/ by hand are deleted by the next expo prebuild --clean.

There are two ways to give Android its icons in Expo.

Vector drawables through the config plugin. Keep the drawable XML files in your project, for example under assets/icons/, and list them in the plugin's android.drawables option. Prebuild copies them into res/drawable, and drawable names then work as in a bare app:

[
"react-native-platform-components/app.plugin",
{ "android": { "drawables": ["./assets/icons"] } }
]
<NavigationRail
items={[
{ label: 'Home', value: 'home', icon: { ios: 'house', android: 'home' } },
]}
selectedValue={selected}
onSelect={setSelected}
/>

Each entry is a .xml file or a directory of them; a drawable is named after its file (assets/icons/home.xml is 'home'), so file names must be lowercase letters, digits and underscores. Make the XML files as described under Android and Your own SVG icons. Run prebuild again after adding or renaming one.

Image icons, which need no native files at all. Every icon prop accepts them:

<FloatingActionButton
label="New"
icon={{
ios: 'plus',
android: { type: 'image', source: require('./assets/plus.png') },
}}
onPress={create}
/>
  • Add plus@2x.png and plus@3x.png beside plus.png so the icon stays sharp; React Native picks the closest scale for the device.
  • Images are drawn as tinted templates, so only the alpha channel matters: draw the shape opaque on a transparent background. An image whose pixels are all transparent draws nothing, even where its color channels hold the shape.
  • Debug builds load the image from Metro; release builds bundle it as a drawable resource.

Image requests (iOS and Android)​

Image icons accept bundled assets or an ImageURISource. Native controls forward uri, scale, headers, method and body. For example:

<Button
label="Account"
icon={{
type: 'image',
tinted: false,
source: {
uri: 'https://example.com/account-icon.png',
headers: { Authorization: `Bearer ${accessToken}` },
cache: 'reload',
},
}}
/>

Use an explicit method such as POST when supplying a UTF-8 request body. Requests that differ by URI, scale, headers, method or body have separate decoded image cache entries. Updating those props reloads the affected icon even when the URI stays the same. Request details are not written to diagnostic logs.

source.cacheNative icon behavior
default (omitted)Reuse a matching decoded image in memory; otherwise load it.
force-cacheSame decoded-image behavior as default.
reloadBypass cached data and refresh the matching decoded image.
only-if-cachedUse a matching decoded image already in memory; render no image on a miss without fetching.

This is the library's bounded in-memory cache, separate from React Native's Image caching. Entries may be evicted and do not persist across app launches. The decoded cache does not revalidate expiry; use reload when the content behind an unchanged request changes. Responses marked Cache-Control: no-store are not kept in it. Only successful HTTP responses are decoded. Requests with custom headers, method or body do not follow redirects; supply the final image URL. Platform transport-security rules still apply. Dimensions come from the image and its scale; width, height, bundle and other source metadata are not additional HTTP request options.

These guarantees apply to the native iOS and Android loaders. Web continues to use its existing image fallback and browser restrictions.

Web​

Browsers have no SF Symbols or drawables, so the web components draw only image icons. Give a per-platform icon a web image, which iOS and Android ignore:

<Button
label="Delete"
icon={{
ios: 'trash',
android: 'delete',
web: { type: 'image', source: require('./icons/trash.png') },
}}
/>

web takes { type: 'image', source, tinted? }: a bundled asset or a { uri }, which can point at an SVG file or be a data: URI. Without web, the web components draw the ios or android source when it is an image. An icon left with nothing to draw renders nothing and logs a warning once in development, naming the symbols or drawables it skipped.

Cross-platform pattern​

Give every icon prop a per-platform set rather than branching on Platform.OS, so one action list serves iOS, Android and the web:

const trashImage = { type: 'image', source: require('./icons/trash.png') } as const;

const actions = [
{
id: 'copy',
title: 'Copy',
image: { ios: 'doc.on.doc', android: 'content_copy' },
},
{
id: 'share',
title: 'Share',
image: { ios: 'square.and.arrow.up', android: 'share' },
},
{
id: 'delete',
title: 'Delete',
image: { ios: 'trash', android: 'delete', web: trashImage },
attributes: { destructive: true },
},
];

An icon that has to show on the web needs a web image, or an image source on every platform. Without one it is left out there, with the development warning described under Web.