🎨 react-native-nitro-sfsymbols

🍎 Render Apple's beautiful SF Symbols natively on iOS with React Native. Zero-bridge overhead, fully typed, production-ready.

📖 Documentation • 🎯 Examples • 🚀 Performance • 📝 API Reference

✨ Features

🎯 Core

🍎 Native SF Symbols on iOS, macOS, tvOS, visionOS
📦 Fully type-safe TypeScript
🚀 Nitro Modules (zero-bridge overhead)
📏 Minimal bundle size (~5KB)
♿ Full accessibility support

🎨 Customization

📐 Any size in points
💪 9 weight levels
📏 3 scale variants
🌈 Multiple color modes
💫 Animations (iOS 17+)
🔄 Variable colors (iOS 16+)

🚀 Quick Start

📦 Installation

npm install react-native-nitro-sfsymbols react-native-nitro-modules

or

yarn add react-native-nitro-sfsymbols react-native-nitro-modules

Important

react-native-nitro-modules is required. Learn more at nitro.margelo.com

⚙️ Setup

cd ios && pod install

🌍 Platform Support

Platform	Support	Minimum Version	Notes
📱 iOS	✅ Full	13.0	Complete SF Symbols support
🖥️ macOS	✅ Full	11.0	Desktop SF Symbols support
📺 tvOS	✅ Full	13.0	TV app SF Symbols support
👓 visionOS	✅ Full	1.0	Spatial computing SF Symbols
🤖 Android	⚠️ Stub	-	Framework ready, requires Material Icons alternative

💡 Basic Usage

import { SFSymbolView, SFIcons } from 'react-native-nitro-sfsymbols';

export function App() {
  return (
    <SFSymbolView 
      name={SFIcons.HEART_FILL}
      size={32}
      tintColor="#FF5722"
    />
  );
}

🎬 Live Demo

Interactive example showcasing color, weight, and scale customization with 400+ available SF Symbols

📚 Usage

🎨 Simple Rendering

import { SFSymbolView, SFIcons } from 'react-native-nitro-sfsymbols';

<SFSymbolView 
  name={SFIcons.THERMOMETER_SUN_FILL}
  size={32}
  tintColor="#FF5722"
/>

📏 Available Symbols

The library includes 400+ curated SF Symbol names organized into 23 categories:

// 🌦️ Weather (15 icons)
SFIcons.THERMOMETER_SUN_FILL
SFIcons.CLOUD_RAIN_FILL
SFIcons.WIND_SNOW

// 🎮 UI Controls (25 icons)
SFIcons.HEART_FILL
SFIcons.STAR_FILL
SFIcons.CHECKMARK_CIRCLE_FILL
SFIcons.XMARK_CIRCLE_FILL

// 🧭 Navigation (30 icons)
SFIcons.CHEVRON_LEFT
SFIcons.ARROW_UP_RIGHT
SFIcons.ARROW_CLOCKWISE
SFIcons.LOCATION_FILL

// 📁 Files (25 icons)
SFIcons.FOLDER_FILL
SFIcons.FILE_FILL
SFIcons.TRASH_FILL

// ... and 400+ more!

Tip

Complete Icon List: See src/icons.ts for the full TypeScript enum with all 400+ available symbols organized by category.

🎯 Complete Iconography

Important

📖 Browse All 400+ Icons: Open src/icons.ts for the comprehensive, type-safe enum of all available SF Symbols organized into 23 categories:

🌦️ Weather (15 icons)
🧭 Navigation & Arrows (30 icons)
🎮 UI Controls (25 icons)
📱 Media & Playback (20 icons)
📤 Share & Action (15 icons)
💬 Communication (20 icons)
🔍 Search & Settings (15 icons)
👤 User & Account (20 icons)
🔐 Security & Protection (15 icons)
📁 File & Document (25 icons)
🛒 Commerce & Shopping (20 icons)
❤️ Activity & Health (31 icons)
🔔 Notification & Alert (12 icons)
🗺️ Maps & Location (20 icons)
⏰ Time & Date (15 icons)
🔷 Shapes & Symbols (20 icons)
📐 Grid & Layout (12 icons)
✏️ Text & Editing (18 icons)
🖼️ Image & Media (15 icons)
🔊 Audio & Music (12 icons)
🔧 Utilities & Tools (20 icons)
🔢 Numbers & Symbols (10 icons)
🎛️ Additional UI Elements (15 icons)

👉 View Complete List with All 400+ Icons →

📚 Usage

⚖️ Weight Customization

Choose from 9 weight levels:

import { SFSymbolView, SFSymbolWeight } from 'react-native-nitro-sfsymbols';

<SFSymbolView 
  name={SFIcons.STAR_FILL}
  size={40}
  weight={SFSymbolWeight.BOLD}
  tintColor="#FFD700"
/>

Available weights:

ULTRALIGHT (100) — Hairline thin
THIN (200)
LIGHT (300)
REGULAR (400) — Default
MEDIUM (500)
SEMIBOLD (600)
BOLD (700)
HEAVY (800)
BLACK (900) — Maximum weight

📏 Scale Variants

import { SFSymbolView, SFSymbolScale } from 'react-native-nitro-sfsymbols';

<SFSymbolView 
  name={SFIcons.BELL_FILL}
  size={24}
  scale={SFSymbolScale.LARGE}
/>

Available scales: SMALL • MEDIUM • LARGE

🌈 Rendering Modes

Monochrome (Default) 🎨

<SFSymbolView 
  name={SFIcons.FOLDER_FILL}
  size={32}
  tintColor="#2196F3"
  renderingMode={SFSymbolRenderingMode.MONOCHROME}
/>

Hierarchical 📊

import { SFSymbolRenderingMode } from 'react-native-nitro-sfsymbols';

<SFSymbolView 
  name={SFIcons.FOLDER_FILL}
  size={32}
  renderingMode={SFSymbolRenderingMode.HIERARCHICAL}
  hierarchical={{
    primaryColor: '#FF5722',
    secondaryColor: '#FF8A65',
    tertiaryColor: '#FFAB91'
  }}
/>

Palette 🎭

<SFSymbolView 
  name={SFIcons.PERSON_3_FILL}
  size={32}
  renderingMode={SFSymbolRenderingMode.PALETTE}
  palette={{
    primaryColor: '#2196F3',
    secondaryColor: '#4CAF50',
    tertiaryColor: '#FFB300'
  }}
/>

🎬 Advanced Features

Opacity 👻

<SFSymbolView 
  name={SFIcons.HEART_FILL}
  size={24}
  opacity={0.6}
/>

Variable Colors (iOS 16+) 🎨

<SFSymbolView 
  name={SFIcons.STAR_FILL}
  size={32}
  variableColor={true}
/>

Animations (iOS 17+) ✨

<SFSymbolView 
  name={SFIcons.BELL_FILL}
  size={32}
  animation={{
    enabled: true,
    type: 'bounce',
    repeating: true
  }}
/>

♿ Accessibility

<SFSymbolView 
  name={SFIcons.HEART_FILL}
  size={24}
  tintColor="#E91E63"
  accessibilityLabel="Add to favorites"
  accessibilityHint="Double tap to add this item to your favorites"
/>

🔧 Utility Functions

Validate Symbols

import { isValidSFIcon, getAllSFIcons } from 'react-native-nitro-sfsymbols';

if (isValidSFIcon('heart.fill')) {
  // render symbol
}

const allIcons = getAllSFIcons(); // Get all available symbols

Search Symbols

import { searchSFIcon } from 'react-native-nitro-sfsymbols';

const icon = searchSFIcon('thermometer'); // Find matching icon

Size Presets

import { getPresetSize } from 'react-native-nitro-sfsymbols';

const size = getPresetSize('large'); // 32pt

🌐 Cross-Platform Usage

Since SF Symbols are iOS-only, use platform detection:

import { Platform } from 'react-native';
import { SFSymbolView, SFIcons } from 'react-native-nitro-sfsymbols';
import MaterialIcon from '@react-native-material/core';

export function Icon({ name }) {
  if (Platform.OS === 'ios') {
    return <SFSymbolView name={name} size={24} />;
  }
  
  // Use Material Icons on Android
  return <MaterialIcon name={name} size={24} />;
}

📊 API Reference

SFSymbolView Props

Prop	Type	Default	Description
`name` ⭐	`SFIcons`	Required	SF Symbol name
`size`	`number`	`24`	Size in points
`weight`	`SFSymbolWeight`	`REGULAR`	Stroke weight (9 levels)
`scale`	`SFSymbolScale`	`MEDIUM`	Scale variant
`tintColor`	`string`	`#000000`	Hex color
`renderingMode`	`SFSymbolRenderingMode`	`MONOCHROME`	Color rendering mode
`hierarchical`	`object`	`undefined`	Hierarchical colors
`palette`	`object`	`undefined`	Palette colors
`animation`	`object`	`undefined`	Animation config (iOS 17+)
`opacity`	`number`	`1`	Opacity 0-1
`variableColor`	`boolean`	`false`	Variable colors (iOS 16+)
`reduceComplexity`	`boolean`	`false`	Reduce for low-end devices
`accessibilityLabel`	`string`	`undefined`	Screen reader label
`accessibilityHint`	`string`	`undefined`	Screen reader hint

Types & Enums

// Symbol names
SFIcons.HEART_FILL
SFIcons.STAR_FILL
SFIcons.THERMOMETER_SUN_FILL
// ... 100+ more

// Weight levels
SFSymbolWeight.ULTRALIGHT | THIN | LIGHT | REGULAR | MEDIUM | SEMIBOLD | BOLD | HEAVY | BLACK

// Scales
SFSymbolScale.SMALL | MEDIUM | LARGE

// Rendering modes
SFSymbolRenderingMode.MONOCHROME | HIERARCHICAL | PALETTE | MULTICOLOR

🚀 Performance

This library is optimized for performance:

✅ Native UIImageView rendering
✅ Nitro Modules (zero-bridge overhead)
✅ Tree-shaking friendly
✅ Memoized props
✅ ~5KB bundle size (gzipped)

💻 Platform Support

Platform	Minimum Version	Status	Notes
🍎 iOS	13.0	✅ Full	Complete SF Symbols support with all features
🖥️ macOS	11.0	✅ Full	Desktop SF Symbols with native rendering
📺 tvOS	13.0	✅ Full	TV app SF Symbols optimized for tvOS
👓 visionOS	1.0	✅ Full	Spatial computing with SF Symbols
🤖 Android	All	⚠️ Stubs	Framework ready, no native SF Symbols support

Warning

Android Note: SF Symbols are exclusive to Apple's platforms (iOS, macOS, tvOS, visionOS). On Android, this library provides placeholder stubs to prevent crashes. Use Material Design Icons instead.

🏗️ Platform-Specific Notes

📱 iOS (13.0+)

Full native support for all SF Symbols features:

✅ All 400+ SF Symbols available
✅ Weight, scale, and rendering modes
✅ Color customization and hierarchical colors
✅ Animations (iOS 17+)

🖥️ macOS (11.0+)

Complete desktop support for SF Symbols:

✅ All iOS features available
✅ Optimized for larger screens
✅ Touch and trackpad interactions
✅ Support for system appearances (light/dark)

📺 tvOS (13.0+)

Optimized for Apple TV:

✅ All SF Symbols available
✅ Focus-based navigation support
✅ Larger default sizes (optimized for TV viewing)
✅ Simplified interactions

👓 visionOS (1.0+)

Built for spatial computing:

✅ All SF Symbols in 3D space
✅ Native visionOS rendering
✅ Gesture-based interactions
✅ Immersive experiences (requires visionOS 1.0+)

🤖 Android

This library provides stub components on Android:

✅ Prevents app crashes
⚠️ Shows placeholder view
📝 Logs helpful warnings
🔗 Suggests alternatives

Alternatives for Android:

🧪 Development

📦 Install Dependencies

yarn install

🔨 Generate Nitro Boilerplate

yarn nitrogen

🧪 Run Tests

yarn test

📋 Type Checking

yarn typecheck

🎨 Linting

yarn lint --fix

🏗️ Build

yarn prepare

Note

Run yarn nitrogen after modifying NitroSfsymbols.nitro.ts

🤝 Contributing

Contributions are welcome and encouraged! 🎉

Please read CONTRIBUTING.md for:

📋 Development workflow
✅ Code style guidelines
🧪 Testing requirements
📤 Pull request process
📖 Code of Conduct

📄 License

↑ back to top

🔗 Resources

Resource	Link
📖 SF Symbols Guide	developer.apple.com/design/human-interface-guidelines/sf-symbols
🎨 SF Symbols Browser	developer.apple.com/sf-symbols
⚡ Nitro Modules Docs	nitro.margelo.com
🚀 React Native Docs	reactnative.dev
🎨 Material Icons	fonts.google.com/icons

Made with ❤️ by Mateus Andrade

Built with create-react-native-library

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
.yarn		.yarn
android		android
example		example
ios		ios
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.nvmrc		.nvmrc
.watchmanconfig		.watchmanconfig
.yarnrc.yml		.yarnrc.yml
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NitroSfsymbols.podspec		NitroSfsymbols.podspec
README.md		README.md
babel.config.js		babel.config.js
eslint.config.mjs		eslint.config.mjs
example.gif		example.gif
lefthook.yml		lefthook.yml
nitro.json		nitro.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
turbo.json		turbo.json
yarn.lock		yarn.lock

License

mCodex/react-native-nitro-sfsymbols

Folders and files

Latest commit

History

Repository files navigation

🎨 react-native-nitro-sfsymbols

✨ Features

🎯 Core

🎨 Customization

🚀 Quick Start

📦 Installation

⚙️ Setup

🌍 Platform Support

💡 Basic Usage

🎬 Live Demo

📚 Usage

🎨 Simple Rendering

📏 Available Symbols

🎯 Complete Iconography

📚 Usage

⚖️ Weight Customization

📏 Scale Variants

🌈 Rendering Modes

Monochrome (Default) 🎨

Hierarchical 📊

Palette 🎭

🎬 Advanced Features

Opacity 👻

Variable Colors (iOS 16+) 🎨

Animations (iOS 17+) ✨

♿ Accessibility

🔧 Utility Functions

Validate Symbols

Search Symbols

Size Presets

🌐 Cross-Platform Usage

📊 API Reference

SFSymbolView Props

Types & Enums

🚀 Performance

💻 Platform Support

🏗️ Platform-Specific Notes

📱 iOS (13.0+)

🖥️ macOS (11.0+)

📺 tvOS (13.0+)

👓 visionOS (1.0+)

🤖 Android

🧪 Development

📦 Install Dependencies

🔨 Generate Nitro Boilerplate

🧪 Run Tests

📋 Type Checking

🎨 Linting

🏗️ Build

🤝 Contributing

📄 License

🔗 Resources

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Languages