Symbols

This library is currently in beta and subject to breaking changes.

expo-symbols provides access to native symbol libraries across platforms. On iOS and tvOS, it uses SF Symbols. On Android and web, it uses Material Symbols.

Installation

bun expo install expo-symbols

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Cross-platform symbols

Pass an object with per-platform symbol names to render symbols on all platforms. Browse available iOS symbols in the Apple SF Symbols app and Android/web symbols at Google Material Symbols.

import { SymbolView } from 'expo-symbols';
import { StyleSheet, View } from 'react-native';

export default function App() {
  return (
    <View style={styles.container}>
      <SymbolView
        name={{ ios: 'info.circle', android: 'info', web: 'info' }}
        tintColor="#007AFF"
        size={35}
      />
      <SymbolView
        name={{
          ios: 'pencil.tip.crop.circle.badge.plus',
          android: 'home_and_garden',
          web: 'home_and_garden',
        }}
        style={styles.symbol}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
  symbol: {
    width: 35,
    height: 35,
    margin: 5,
  },
});

If you only pass a string, it is treated as an SF Symbol name and renders only on iOS. On Android and web, nothing will be rendered unless you provide a fallback:

{
  /* iOS-only: pass an SF Symbol name directly */
}
<SymbolView name="airpods.chargingcase" style={styles.symbol} type="hierarchical" />;

{
  /* Use fallback for platforms where the symbol is not defined */
}
<SymbolView name={{}} fallback={<Text>?</Text>} />;

Weights

On iOS, pass a weight string directly. On Android, import a weight object from expo-symbols/androidWeights:

import bold from 'expo-symbols/androidWeights/bold';

<SymbolView
  name={{ ios: 'star.fill', android: 'star', web: 'star' }}
  weight={{ ios: 'bold', android: bold }}
  tintColor="gold"
  size={35}
/>;

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

API

import { SymbolView } from 'expo-symbols';

Component

SymbolView

Type: React.Element<SymbolViewProps>

SymbolViewProps

animationSpec

Optional • Type: AnimationSpec

The animation configuration to apply to the symbol.

colors

Optional • Literal type: union

An array of colors to use when the SymbolType is palette.

Acceptable values are: ColorValue | ColorValue[]

fallback

Optional • Type: React.ReactNode

Fallback to render when a symbol for the given platform is not defined.

name

Literal type: union

The name of the symbol. iOS Symbols can be viewed in the Apple SF Symbols app.

Acceptable values are: SFSymbol | { android: AndroidSymbol, ios: SFSymbol, web: AndroidSymbol }

resizeMode

Optional • Type: ContentMode • Default: 'scaleAspectFit'

Determines how the image should be resized to fit its container.

scale

Optional • Type: SymbolScale • Default: 'unspecified'

The scale of the symbol to render.

size

Optional • Type: number • Default: 24

The size of the symbol.

tintColor

Optional • Type: ColorValue

The tint color to apply to the symbol.

type

Optional • Type: SymbolType • Default: 'monochrome'

Determines the symbol variant to use.

weight

Optional • Literal type: union • Default: 'unspecified'

The weight of the symbol to render. On Android and web import from expo-symbols/androidWeights/{weight}.

Acceptable values are: SymbolWeight | { android: AndroidSymbolWeight, ios: SymbolWeight }

Inherited props

• ViewProps

Methods

Types

AnimationEffect

AnimationSpec

The animation configuration to apply to the symbol.

AnimationType

Literal type: string

The type of animation to apply to the symbol.

Acceptable values are: 'bounce' | 'pulse' | 'scale'

ContentMode

Literal type: string

Determines how the image should be resized to fit its container.

Acceptable values are: 'scaleToFill' | 'scaleAspectFit' | 'scaleAspectFill' | 'redraw' | 'center' | 'top' | 'bottom' | 'left' | 'right' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight'

SymbolScale

Literal type: string

The scale of the symbol to render.

Acceptable values are: 'default' | 'unspecified' | 'small' | 'medium' | 'large'

SymbolType

Literal type: string

Determines the symbol variant to use.

• 'monochrome' - Creates a color configuration that specifies that the symbol image uses its monochrome variant.

• 'hierarchical' - Creates a color configuration with a color scheme that originates from one color.

• 'palette' - Creates a color configuration with a color scheme from a palette of multiple colors.

• 'multicolor' - Creates a color configuration that specifies that the symbol image uses its multicolor variant, if one exists.

Acceptable values are: 'monochrome' | 'hierarchical' | 'palette' | 'multicolor'

SymbolWeight

Literal type: string

The weight of the symbol to render.

Acceptable values are: 'unspecified' | 'ultraLight' | 'thin' | 'light' | 'regular' | 'medium' | 'semibold' | 'bold' | 'heavy' | 'black'

VariableAnimationSpec

A variable color animation draws attention to a symbol by changing the opacity of the symbol’s layers. You can choose to apply the effect to layers either cumulatively or iteratively. For cumulative animations, each layer’s opacity remains changed until the end of the animation cycle. For iterative animations, each layer’s opacity changes briefly before returning to its original state. These effects are compounding, each value set to true will add an additional effect.

Sources

The original Expo docs for this page:

• Symbols (source-of-truth/versions/v57.0.0/sdk/symbols.md)