react-native-sfsymbol

NOTE: This library is under development, so the API may change until it hits v1.0.0.

SF Symbols are a set of over 2,500 consistent, highly configurable symbols you can use in your app. SF Symbols are designed to integrate seamlessly with the San Francisco system font, so the symbols automatically ensure optical vertical alignment with text for all weights and sizes.

Highlights

• :fire: Built with Expo's Module API
• :art: Support for all rendering modes
• :loud_sound: Support for variable color values
• :apple: iOS only (see why)

Installation

Add the package as a dependency

yarn add react-native-sfsymbol

Then run

npx pod-install

NOTE: This library works with bare React Native and Expo managed apps. It will not work with Expo Go.

Usage

import { useState } from "react";
import { View, Button } from "react-native";
import { SFSymbol } from "react-native-sfsymbol";

export default function App() {
  const [volume, setVolume] = useState(0);
  return (
    <View style={styles.container}>
      {/* Monochrome rendering mode (one color) */}
      <SFSymbol
        name="heart"
        color="#FF3B30FF"
        weight="bold"
        size={100}
        scale="small"
      />
      {/* Hierarchical rendering mode (one color with opacities), with a varaible value */}
      <SFSymbol
        name="speaker.wave.3"
        renderingMode="hierarchical"
        scale="medium"
        variableValue={volume}
        size={100}
      />
      <Button title="Volume Up" onPress={() => setVolume(volume + 0.1)} />
      {/* Palette rendering mode (multiple custom colors) */}
      <SFSymbol
        name="person.2"
        renderingMode="palette"
        color={["#FF3B30FF", "#007AFFFF"]}
        size={100}
      />
      {/* Multicolor rendering mode (pre-determined system colors) */}
      <SFSymbol
        name="phone.arrow.up.right"
        renderingMode="multicolor"
        size={100}
      />
    </View>
  );
}

<SFSymbol />

The SFSymbol component uses UIKit's UIImage view to render SF Symbols.

Props

name

The name of the symbol.

required: yes

type: SystemName

default: ""

color

The color of the symbol. This can be a single color or an array of colors depending on the rendering mode.

required: no

type: string or string[]

default: "#007AFFFF"

weight

The weight of the symbol.

required: no

type: "thin" | "ultraLight" | "light" | "regular" | "medium" | "semibold" | "bold" | "heavy" | "black"

default: "regular"

scale

The scale of the symbol.

required: no

type: "small" | "medium" | "large"

default: "small"

renderingMode

The rendering mode of the symbol.

required: no

type: "monochrome" | "hierarchical" | "palette" | "multicolor"

default: "monochrome"

size

The size of the symbol. This deifines the frame of the image view.

required: no

type: number

default: 42

variableValue

The variable value of the symbol.

required: no

type: number

default: 1.0

style

The style of the symbol.

required: no

type: StyleProp<ViewStyle>

default: undefined