react-native-sfsymbol

React Native Fabric component for rendering SF Symbols on iOS and Material Symbols on Android.

Requires React Native 0.76+ (New Architecture / Fabric).

Features

• SF Symbols on iOS (6,000+ system icons)
• Material Symbols on Android (2,500+ icons via bundled font)
• Platform-specific icon names with a single component
• Customizable color, size, weight (iOS), and scale (iOS)
• PlatformColor support on iOS
• Fallback image support
• Fabric / New Architecture only

Installation

npm install @dariyd/react-native-sfsymbol
# or
yarn add @dariyd/react-native-sfsymbol

Then install iOS pods:

cd ios && pod install

No extra setup is needed for Android — the Material Symbols font is bundled with the library.

Usage

Basic usage (same icon name on both platforms)

import SFSymbolIcon from 'react-native-sfsymbol';

<SFSymbolIcon
  name="star"
  color="black"
  style={{ width: 24, height: 24 }}
/>

Platform-specific icon names

SF Symbols and Material Symbols have different naming conventions. Use an object to specify different names per platform:

<SFSymbolIcon
  name={{ ios: 'house', android: 'home' }}
  color="black"
  style={{ width: 28, height: 28 }}
/>

<SFSymbolIcon
  name={{ ios: 'gear', android: 'settings' }}
  color="black"
  style={{ width: 28, height: 28 }}
/>

<SFSymbolIcon
  name={{ ios: 'person.crop.circle', android: 'person' }}
  color="black"
  style={{ width: 28, height: 28 }}
/>

Colors

<SFSymbolIcon
  name={{ ios: 'heart.fill', android: 'favorite' }}
  color="red"
  style={{ width: 28, height: 28 }}
/>

// PlatformColor (iOS only)
import { PlatformColor, Platform } from 'react-native';

<SFSymbolIcon
  name="heart.fill"
  color={Platform.OS === 'ios' ? PlatformColor('systemPinkColor') : 'pink'}
  style={{ width: 28, height: 28 }}
/>

Weight (iOS only)

Controls the stroke thickness of SF Symbols. Most visible on outlined (non-filled) symbols.

<SFSymbolIcon
  name={{ ios: 'heart', android: 'favorite' }}
  weight="ultralight"
  style={{ width: 28, height: 28 }}
/>

<SFSymbolIcon
  name={{ ios: 'heart', android: 'favorite' }}
  weight="bold"
  style={{ width: 28, height: 28 }}
/>

Available weights: ultralight, thin, light, regular, medium, semibold, bold, heavy, black

Size

On iOS, size sets the point size for the SF Symbol configuration. On Android, size sets the font size in dp for the Material Symbol.

<SFSymbolIcon
  name={{ ios: 'star.fill', android: 'star' }}
  size={32}
  style={{ width: 32, height: 32 }}
/>

Fallback image

When name is not provided, a fallback image can be displayed:

<SFSymbolIcon
  fallbackImage={require('./assets/icon.png')}
  style={{ width: 24, height: 24 }}
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | name | string \| { ios?: string; android?: string } | — | Icon name. String for same name on both platforms, or object for platform-specific names | | size | number | 17 | Point size (iOS) / font size in dp (Android) | | weight | string | 'regular' | Symbol weight (iOS only): ultralight, thin, light, regular, medium, semibold, bold, heavy, black | | scale | string | 'medium' | Symbol scale (iOS only): small, medium, large | | color | ColorValue | System default | Tint color. Supports PlatformColor() on iOS | | renderingMode | string | 'template' | 'template' (tintable) or 'original' (multicolor, iOS only) | | fallbackImage | ImageSource | — | Fallback image when name is not provided | | style | ViewStyle | — | Container style (controls the visual size of the icon) |

How it works

iOS

Uses native SF Symbols via UIImage(systemName:) rendered in a UIImageView. Supports all SF Symbol configuration options including weight, scale, and rendering mode. Falls back to UIImage(named:) for custom icons in your Xcode asset catalog.

Android

Uses Google Material Symbols font bundled with the library. Icons are rendered via font ligatures in a TextView — setting the text to an icon name like "home" renders the corresponding glyph. No additional setup or drawable resources required.

Finding icon names

• iOS (SF Symbols): Download the SF Symbols app to browse all available icons
• Android (Material Symbols): Browse icons at Google Fonts Icons and use the icon name (e.g., home, settings, favorite, person)

Common icon name mappings

| Description | iOS (SF Symbol) | Android (Material Symbol) | |-------------|----------------|--------------------------| | Home | house | home | | Settings | gear | settings | | Star (filled) | star.fill | star | | Star (outline) | star | star_outline | | Heart (filled) | heart.fill | favorite | | Heart (outline) | heart | favorite_border | | Person | person.crop.circle | person | | Search | magnifyingglass | search | | Close | xmark | close | | Share | square.and.arrow.up | share | | Delete | trash | delete | | Edit | pencil | edit | | Add | plus | add | | Check | checkmark | check | | Info | info.circle | info | | Warning | exclamationmark.triangle | warning | | Camera | camera | photo_camera | | Photo | photo | image | | Location | location | location_on | | Bookmark | bookmark | bookmark |

License

MIT