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:
- Create vector drawable XML files in
android/app/src/main/res/drawable/ - Use Material Icons as a source — download SVG and convert to Android Vector Drawable
- Name the file to match the
imageprop value (e.g.,content_copy.xmlforimage: '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
.svginto 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 namedmy.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, intores/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.pngandplus@3x.pngbesideplus.pngso 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.cache | Native icon behavior |
|---|---|
default (omitted) | Reuse a matching decoded image in memory; otherwise load it. |
force-cache | Same decoded-image behavior as default. |
reload | Bypass cached data and refresh the matching decoded image. |
only-if-cached | Use 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.