⚡️ React Native Nitro Symbols

A high-performance, type-safe SF Symbols library for React Native, built with Nitro Modules and SwiftUI.

Render native iOS SF Symbols with animation support, multiple rendering modes, and complete TypeScript autocomplete.

✨ Features

• 🚀 Nitro Powered – Near-zero-overhead JSI bridging for maximum performance
• 🎨 Multiple Rendering Modes – Monochrome, hierarchical, palette, and multicolor
• ✨ Native Animations – Support for Discrete (one-shot), Indefinite (looping), and Transition effects
• 🎭 Symbol Variants – Fill, slash, circle, square, and rectangle variants
• 🔤 Typography Control – Full control over weight (9 options) and scale (3 options)
• 🎨 Multi-Color Support – Use up to 3 colors with palette rendering mode
• 🌈 Flexible Color Formats – Supports named colors, hex, RGB, RGBA, and HSL color strings
• 📝 Full TypeScript Support – Complete autocomplete for all SF Symbol names and props

📋 Requirements

• iOS 17.0+ for core functionality
• iOS 18.0+ for advanced effects (Wiggle, Rotate, Breathe)
• iOS 26.0+ for the Draw-on effect
• New Architecture enabled

IMPORTANT This library cannot be used with Expo Go due to custom native Swift code. You must use a development build.

📦 Installation

# Install the library
npm install react-native-nitro-symbols

# Install required peer dependency
npm install react-native-nitro-modules

# For Expo projects
npx expo prebuild

# Install iOS pods
cd ios && pod install && cd ..

# Run the app
npx expo run:ios

🎨 Uniwind Integration (Optional)

This library works seamlessly with Uniwind, bringing Tailwind CSS utility classes to React Native.

To use Tailwind classes with SymbolView, follow the Uniwind Quickstart to set up your project.

Wrap Components (for custom components like SymbolView):

import { withUniwind } from 'uniwind';
import { SymbolView } from 'react-native-nitro-symbols';

const StyledSymbolView = withUniwind(SymbolView);

Use Tailwind Classes:

<StyledSymbolView
  symbolName="heart.fill"
  className="w-12 h-12 text-red-500"
/>

For an example of how to use Uniwind with the component, check out: UniwindDemo.tsx

For complete setup instructions, see the Uniwind Quickstart.

🚀 Quick Start

import { SymbolView } from 'react-native-nitro-symbols'

export default function App() {
  return (
    <SymbolView
      symbolName="heart.fill"
      tintColor="#FF3B30"
      pointSize={50}
      weight="bold"
    />
  )
}

📚 API Reference

Props

| Prop | Type | Default | Description | | --------------- | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------- | | symbolName | SFSymbol | required | Name of the SF Symbol with full autocomplete support | | pointSize | number | 24 | Font size of the symbol in points | | weight | SymbolWeight | "regular" | Symbol weight: ultralight, thin, light, regular, medium, semibold, bold, heavy, black | | scale | SymbolScale | "medium" | Image scale: small, medium, large | | tintColor | ColorValue | undefined | Color for monochrome rendering. Supports named colors ("red"), hex ("#FF0000"), RGB, RGBA, HSL | | colors | ColorValue[] | undefined | Array of colors for palette rendering (up to 3 colors). Supports all React Native color formats | | renderingMode | SymbolRenderingMode | "monochrome" | Rendering mode: monochrome, hierarchical, palette, multicolor | | variant | SymbolVariant | undefined | Symbol variant: fill, slash, circle, square, rectangle | | effect | SFSymbolEffect | undefined | Animation effect. See Animation Effects below. | | isAnimating | boolean | false | Trigger for discrete effects (change value to trigger) or toggle for indefinite loops. | | isVisible | boolean | true | Required for the appear effect to trigger exit animations correctly. | | fallback | ReactNode | undefined | (Android/Web only) React node to render on non-iOS platforms (e.g. Ionicons, Text). |

💡 Examples

Basic Symbol

<SymbolView
  symbolName="star.fill"
  tintColor="gold" // Named color
  pointSize={60}
  weight="bold"
/>

Palette Rendering (Multi-Color)

<SymbolView
  symbolName="theatermasks"
  renderingMode="palette"
  colors={['purple', '#8E8E93']} // Mix named colors and hex
  pointSize={60}
  weight="bold"
/>

Discrete Animation (Wiggle/Bounce)

Change the isAnimating prop to trigger the effect once.

import { useState } from 'react'

export function NotificationBell() {
  const [trigger, setTrigger] = useState(false)

  return (
    <TouchableOpacity onPress={() => setTrigger(!trigger)}>
      <SymbolView
        symbolName="bell.badge.fill"
        colors={['red', 'black']} // Named colors
        renderingMode="palette"
        pointSize={80}
        effect="wiggle"
        isAnimating={trigger}
      />
    </TouchableOpacity>
  )
}

Indefinite Animation (Breathe/Rotate)

Set isAnimating to true to loop forever.

<SymbolView
  symbolName="lungs.fill"
  tintColor="rgba(50, 173, 230, 1)" // RGBA format
  pointSize={80}
  effect="breathe"
  isAnimating={true}
/>

Magic Replace (Content Transition)

Simply change the symbolName while effect="replace" is active.

<SymbolView
  symbolName={isAuthenticated ? 'checkmark.circle.fill' : 'faceid'}
  effect="replace"
  tintColor={isAuthenticated ? 'green' : 'black'} // Named colors
  pointSize={80}
/>

Appear / Disappear Transition

WARNING Crucial: Do not unmount the component. Use isVisible prop and fixed dimensions. See example app for more details on usage.

<View>
  {/* The symbol stays mounted to play the exit animation */}
  <SymbolView
    symbolName="swift"
    pointSize={80}
    isVisible={showIcon}
    effect="appear"
  />
</View>

✨ Animation Effects

This library maps isAnimating intelligently based on the effect type:

1. Discrete Effects (One-Shot)

Change isAnimating (true -> false or false -> true) to trigger once.

| Effect | iOS Version | Description | | ----------- | ----------- | -------------------------------------------------- | | wiggle | 18.0+ | Wiggles the symbol side to side (e.g., for alerts) | | bounce | 17.0+ | Bounces the symbol (e.g., for notifications) | | scaleup | 18.0+ | Scales the symbol up momentarily | | scaledown | 18.0+ | Scales the symbol down momentarily |

2. Indefinite Effects (Looping)

Set isAnimating={true} to loop, {false} to stop.

| Effect | iOS Version | Description | | --------------- | ----------- | ------------------------------------------- | | breathe | 18.0+ | Smoothly fades opacity in and out | | rotate | 18.0+ | Rotates the symbol continuously | | pulse | 17.0+ | Pulses the opacity (e.g., recording status) | | variablecolor | 18.0+ | Cycles opacity through layers |

3. Transitions

Controlled by specific props.

| Effect | Prop | Description | | --------- | ------------- | ----------------------------------------------- | | replace | symbolName | Morphs the vector paths when the name changes | | appear | isVisible | Scales/Fades in and out when visibility changes | | drawon | isAnimating | Draws the symbol path (writing effect) |

🌍 Cross-Platform Support (Android/Web)

Since SF Symbols are Apple-proprietary, this library is iOS-only. However, you can use the fallback prop to gracefully handle other platforms.

The fallback prop accepts any React Node, allowing you to render alternative icons (like react-native-vector-icons or lucide-react-native) on Android and Web.

import { SymbolView } from 'react-native-nitro-symbols'
import Ionicons from '@expo/vector-icons/Ionicons'

;<SymbolView
  symbolName="star.fill"
  tintColor="gold"
  fallback={<Ionicons name="star" size={24} color="gold" />}
/>

For a complete example of how to build a cross-platform icon component, check out: FallbackDemo.tsx

🔍 Symbol Discovery

This library provides full TypeScript autocomplete for all SF Symbol names. When you type symbolName=", your IDE will suggest all available symbols.

You can also browse symbols at: SF Symbols App (macOS)

🛠️ Troubleshooting

"Cannot be used with Expo Go"

This library requires custom native code. Create a development build:

npx expo prebuild
npx expo run:ios

"Invariant Violation: View config getter callback..."

Ensure you do not have two instaces of react-native running at the same time.

Animations not playing

• Check that you are on the supported iOS version (many effects need iOS 18).
• For .appear transitions, ensure you are using the isVisible prop and not conditionally unmounting the component in React Native.
• For .appear, ensure the component has a fixed width and height style.

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by Davey Eke for the React Native community