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)