Skip to content

Symbols

@symbiote-native/symbols wraps expo-symbols, so every SymbioteNative adapter can draw SF Symbols on iOS and Material Symbols on Android, not just React. On Android the glyph comes from a font loaded through @symbiote-native/font.

Terminal window
npm install @symbiote-native/symbols

Scaffolding or extending a SymbioteNative app? npx @symbiote-native/cli new --symbols (or add --symbols in an existing app) installs and wires this for you.

name is an SF Symbols name, or an object with an entry per platform. When the current platform has no entry the component renders its fallback.

import { SymbolView } from '@symbiote-native/symbols/react';
<SymbolView
name={{ ios: 'star.fill', android: 'star' }}
tintColor="orange"
size={32}
fallback={<Text>star</Text>}
/>;
Prop Description
name An SF Symbols name or { ios, android, web }
type iOS: monochrome (default), hierarchical, palette, multicolor
scale iOS symbol scale
weight A weight name, or { ios, android } with an Android weight import
colors iOS palette colors
size Default 24
tintColor Android default is the system primary color
resizeMode iOS content mode
animationSpec iOS symbol effects

Plus style, testID, nativeID, onLayout and the accessibility and responder props every View takes. On Android only style reaches the drawn View, as in upstream.

unstable_getMaterialSymbolSourceAsync(symbol, size, color) renders a Material Symbol to an image source for APIs that take an image, such as tab bar icons.

The Android font weight is imported from a subpath, so only the weights an app uses are bundled:

import bold from '@symbiote-native/symbols/androidWeights/bold';
// weight={{ ios: 'bold', android: bold }}

Available: thin, extraLight, light, regular, medium, semiBold, bold.

  • name is per platform. SF Symbols and Material Symbols use different names, so pass { ios: 'heart.fill', android: 'favorite' }. A platform with no entry renders your fallback.
  • Android draws a glyph, not an image. The view is an empty sized View until the font loads, then the glyph is a Text in the Material Symbols font. If loading fails it stays empty.
  • size sets width and height (24 by default). On Android style goes to that wrapping View, so margins and backgrounds apply there too.
  • Only the weights you import are bundled on Android. regular is the default, any other comes from the androidWeights subpath. Do not import weights you do not use.
  • tintColor goes through the same color processing as every other view, so names, hex, rgb() and rgba() all work. On Android it is the text color, and the default is the system primary color.

The icon is blank on Android. The Material Symbols font loads asynchronously, and until it does the view is an empty box of size by size. If it stays empty, the font failed to load or the name does not exist as a Material Symbol: check the spelling against the Material Symbols list, and that you passed an android entry in name. Render a fallback for the in-between state if the layout cannot tolerate an empty box.

Symbols look stretched on iOS. SF Symbols are not square, so a fixed width and height squeezes the wide ones, which is why the lens of the camera symbol turns oval. Set resizeMode (scaleAspectFit keeps the proportions) instead of forcing both dimensions.

Filled and outline states do not switch on Android. The bundled Material Symbols fonts are static instances without the FILL axis, and the legacy *_filled code points are aliased to the outline glyph. Switching favorite_border and favorite therefore shows the outline both times. This is open upstream. Pick two icons that differ in shape, or draw the filled state yourself.

Does an rgb() color work? Yes, tintColor and colors go through the same color processing as every other view. A report that SymbolView ignored rgb() in a tab bar was traced upstream to the custom tabBarIcon not reacting to the tint change, not to the color format. If a symbol keeps an old color, check that the tint reaches the component again when it changes.

How big is the Android font? Each weight is its own file, around a megabyte, and the weights are separate subpaths, so only those you import reach the bundle. Upstream’s expo-router pulls all seven weights in even when unused, a problem that does not apply to this package.

Can I use a symbol as an image, for a tab bar? unstable_getMaterialSymbolSourceAsync(symbol, size, color) renders a Material Symbol to an image source for APIs that take an image.

Can I use my own SF Symbol? The native view takes system SF Symbol names. Custom symbols exported from the SF Symbols app are not covered by this package.

Sources:

expo-symbols’ JS is hand-ported into this package’s core/: the prop types, the per-platform name resolution, the Material Symbols table and the descriptors. On iOS renderSymbolView returns the native SymbolView with every prop forwarded. Elsewhere it returns a sized View holding a Text in the Material Symbols font, loaded once on mount through @symbiote-native/font. The descriptor shape changes when the font arrives, from an empty View to a View with a glyph. So each adapter rebuilds the node for that change. fallback is each framework’s own idiom (a prop, a slot, a snippet, projected content).

The native code is never vendored: expo-modules-autolinking resolves it from node_modules (see the native setup guide).