@huymobile/react-native-iconify

200,000+ icons for React Native and Web with platform-aware caching

---

Why react-native-iconify?

Traditional icon libraries require you to bundle all icons at build time, leading to:

• ❌ Large bundle sizes (even if you use only 10 icons)
• ❌ Manual imports for each icon
• ❌ Limited icon selection per library

react-native-iconify takes a different approach:

• ✅ 200,000+ icons from 150+ icon sets (Material Design, Feather, Heroicons, Phosphor, Lucide, and more)
• ✅ Load icons by name - no imports needed
• ✅ Zero bundle size impact in development
• ✅ Automatic bundling for production builds
• ✅ Platform-aware caching with SDWebImage (iOS), Glide (Android), and an in-memory web cache

---

Features

Feature	Description
🎨 200,000+ Icons	Access to 150+ icon sets from Iconify
⚡ Zero Config	Works out of the box - no manual bundling required
📦 Auto-Bundling	Icons automatically bundled during production builds (APK/IPA)
💾 Native Caching	SDWebImage (iOS) + Glide (Android) for persistent storage
🏗️ New Architecture	Full support for React Native 0.68+ New Architecture
📱 Old Architecture	Backward compatible with React Native 0.60+
🚀 Expo Support	Works with Expo development builds and EAS
🔧 React Native CLI	Full support for bare React Native projects
🌐 Web Support	Same component and import on React Native Web and Expo Web

---

Compatibility

Platform	Minimum Version
React Native	0.68.0+
React Native (Old Arch)	0.60.0+
Expo SDK	49+
React Native Web	0.19+
iOS	13.0+
Android	API 21+ (Android 5.0)

---

Installation

# Using npm
npm install @huymobile/react-native-iconify react-native-svg

# Using yarn
yarn add @huymobile/react-native-iconify react-native-svg

# Using pnpm
pnpm add @huymobile/react-native-iconify react-native-svg

# Using bun
bun add @huymobile/react-native-iconify react-native-svg

iOS Setup

cd ios && pod install

Expo Setup

npx expo install react-native-svg
npx expo prebuild

Note: react-native-iconify requires a development build. It will not work with Expo Go.

This native-build requirement applies to iOS and Android. Expo Web uses the JavaScript in-memory cache and does not load a native cache module.

---

Quick Start

import React from 'react';
import { View } from 'react-native';
import { IconifyIcon } from '@huymobile/react-native-iconify';

export default function App() {
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      {/* Material Design Icons */}
      <IconifyIcon name="mdi:home" size={32} color="#333" />

      {/* Heroicons */}
      <IconifyIcon name="heroicons:user-solid" size={32} color="blue" />

      {/* Feather Icons */}
      <IconifyIcon name="feather:settings" size={32} color="green" />

      {/* Phosphor Icons */}
      <IconifyIcon name="ph:heart-fill" size={32} color="red" />
    </View>
  );
}

Finding Icons

Browse and search icons at icon-sets.iconify.design

Icon names follow the format: {prefix}:{icon-name}

Examples:

• mdi:home - Material Design Icons
• heroicons:user - Heroicons
• feather:settings - Feather Icons
• lucide:camera - Lucide Icons
• ph:heart - Phosphor Icons

---

API

IconifyIcon Props

Prop	Type	Default	Description
name	string	required	Icon name in format prefix:name
size	number	24	Icon size (width & height)
color	string	#000	Icon color
rotate	number	0	Rotation in degrees
flip	'horizontal' | 'vertical' | 'both'	-	Flip the icon
style	ViewStyle	-	Additional styles
onLoad	() => void	-	Called when icon loads successfully
onError	(error: Error) => void	-	Called when icon fails to load
fallback	ReactNode	-	Fallback component while loading
testID	string	-	Test ID for testing

Examples

// Basic usage
<IconifyIcon name="mdi:home" size={24} color="blue" />

// With rotation
<IconifyIcon name="mdi:arrow-right" size={24} rotate={90} />

// With flip
<IconifyIcon name="mdi:arrow-left" size={24} flip="horizontal" />

// With custom fallback
<IconifyIcon
  name="mdi:home"
  size={24}
  fallback={<ActivityIndicator size="small" />}
/>

// With callbacks
<IconifyIcon
  name="mdi:home"
  size={24}
  onLoad={() => console.log('Icon loaded!')}
  onError={(err) => console.error('Failed:', err)}
/>

---

Icon Sets

react-native-iconify supports 150+ icon sets with over 200,000 icons.

Popular Icon Sets

Icon Set	Prefix	Icons	License
Material Design Icons	mdi	7,000+	Apache 2.0
Heroicons	heroicons	290+	MIT
Feather Icons	feather	280+	MIT
Phosphor	ph	7,000+	MIT
Lucide	lucide	1,400+	ISC
Tabler Icons	tabler	4,400+	MIT
Bootstrap Icons	bi	1,900+	MIT
Font Awesome	fa6-solid	1,400+	CC BY 4.0
Remix Icons	ri	2,700+	Apache 2.0
Carbon	carbon	2,000+	Apache 2.0

Browse all icon sets at icon-sets.iconify.design

---

Architecture Support

New Architecture (Fabric + TurboModules)

react-native-iconify fully supports React Native's New Architecture:

• ✅ TurboModules for native cache access
• ✅ Fabric-compatible rendering
• ✅ Concurrent features support

Old Architecture (Bridge)

Backward compatible with the bridge-based architecture:

• ✅ Works with React Native 0.60+
• ✅ Standard Native Modules
• ✅ Full feature parity

---

Expo Support

Development Builds

# Install
npx expo install @huymobile/react-native-iconify react-native-svg

# Create development build
npx expo prebuild
npx expo run:ios
# or
npx expo run:android

EAS Build

# Build for production
eas build --platform all

Expo Go

⚠️ Not Supported: react-native-iconify requires native modules and will not work with Expo Go. Use a development build instead.

Web

React Native Web and Expo Web use the same component and import as iOS and Android—an app-level .web.tsx wrapper is not required:

import { IconifyIcon } from '@huymobile/react-native-iconify';

export function AppIcon() {
  return <IconifyIcon name="mdi:web" size={32} color="#2563eb" />;
}

Web caching is in memory and resets when the page reloads. iOS and Android continue to use their persistent native cache backends.

---

Performance

Scenario	Load Time
Bundled icon (production)	0ms
Native cache hit	15-35ms
Web memory cache hit	<1ms
API fetch (first load)	200-500ms

---

Troubleshooting

Icons not loading

1. Check internet connection (for API fetches)
2. Verify icon name format: prefix:icon-name
3. Check if icon exists at icon-sets.iconify.design

iOS build errors

cd ios && pod install --repo-update

Android build errors

cd android && ./gradlew clean

Metro bundler issues

npx react-native start --reset-cache

---

Credits

• Iconify - The universal icon framework
• react-native-svg - SVG rendering for React Native
• SDWebImage - iOS image caching
• Glide - Android image caching