Elevate your React Native applications with the power of customizable vector icons. Ideal for embellishing buttons, logos, and navigation or tab bars, these icons seamlessly integrate into your projects. Their versatility makes extension and styling effortless.
Should you find this library beneficial, kindly contemplate the option of sponsoring. Our envisioned endeavors encompass the restructuring of the repository into a monorepo architecture. This transition will empower independent versioning of icon sets, enhance performance, reduce bundle size, and simplify community contributions. Your sponsorship plays a pivotal role in materializing these advancements.
Monorepo configuration
If working in a monorepo, point to the correct paths of the `fonts.gradle` script and of the Font files, relative to the android/app/build.gradle file. Example structure:
⚠️ Reported issues have arisen when utilizing RNVI versions earlier than 9.0.0 within a monorepo context. Therefore, it's advisable to ensure your RNVI version is 9.0.0 or later.
Option: Manual Integration
To manually integrate the library, follow these steps:
Copy the contents from the Fonts folder and paste them into android/app/src/main/assets/fonts (ensure the folder name is lowercase, i.e., fonts).
Integrating Library for getImageSource Support
The following steps are optional and are only necessary if you intend to utilize the Icon.getImageSource function.
Edit the android/settings.gradle file as shown below:
rootProject.name = 'MyApp'include ':app'+ include ':react-native-vector-icons'+ project(':react-native-vector-icons').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-vector-icons/android')
Edit the android/app/build.gradle (located in the app folder) as shown below:
To set up the library on your macOS project using react-native-macos, follow these steps:
Browse to the node_modules/react-native-vector-icons folder and drag the Fonts folder into your project in Xcode. Ensure that your app is checked under "Add to targets," and select "Create folder references" when prompted.
Edit your Info.plist and include a new property named Application fonts resource path (or ATSApplicationFontsPath if Xcode's autocomplete isn't functioning or you're not using Xcode). Set the value of this property to Fonts.
From your project's /ios folder run:
bundle exec pod install
Please note that after adding new fonts, you need to recompile your project. Also, make sure that the Fonts folder is present under the Copy Bundle Resources section within the Build Phases of your Xcode project.
These steps will effectively integrate the vector icons library into your macOS project while utilizing the react-native-macos framework.
To set up the library on your Windows project using react-native-windows, follow these steps:
In the top-level projects (/windows/project-name/Assets), copy and paste the font files.
Open your solution in Visual Studio:
a. Right-click the Assets folder in your solution.
b. Select Add > Existing Item.
c. Browse and select the fonts that you copied into /windows/project-name/assets.
d. Click Add.
Please note that after adding new fonts, you need to recompile your project.
By following these steps, you'll seamlessly integrate the vector icons library into your Windows project, leveraging the react-native-windows framework.
React-native-web Setup
To port a react-native mobile app to web using react-native-web you just need to ensure the fonts are known on the web-app side.
You will need add the font-family for each font you use to your css
You can debug missing font-families by looking in the Developer console in your web browser when debugging your web app.
NOTE: if you're using webpack or similar you may need to configure webpack to handle loading of ttf fonts, using url-loader or file-loader. See Web Setup for more details.
In your App.css or similar add the font-family specifications:
In your JavaScript entry point, consume the font files and inject the necessary style tag:
// Use the prebuilt version of RNVI located in the dist folder import Icon from 'react-native-vector-icons/dist/FontAwesome'; // Generate the required CSS import iconFont from 'react-native-vector-icons/Fonts/FontAwesome.ttf'; const iconFontStyles = `@font-face { src: url(${iconFont}); font-family: FontAwesome; }`; // Create a stylesheet const style = document.createElement('style'); style.type = 'text/css'; // Append the iconFontStyles to the stylesheet if (style.styleSheet) { style.styleSheet.cssText = iconFontStyles; } else { style.appendChild(document.createTextNode(iconFontStyles)); } // Inject the stylesheet into the document head document.head.appendChild(style);
By following these steps, you will seamlessly integrate the vector icons library into your web project using webpack, enabling you to effortlessly use the icons within your web application.
Upgrading
Upgrading this package often requires the font files linked to your projects to be updated as well. If the automatic linking works for you, running this again should update the fonts. Otherwise you need to follow the steps outlined in the installation section.
Icon Component
You can either use one of the bundled icons above or roll your own custom font.
Size of the icon, can also be passed as fontSize in the style object.
12
name
What icon to show, see Icon Explorer app or one of the links above.
None
color
Color of the icon.
Inherited
Static Methods
Prop
Description
getFontFamily
Returns the font family that is currently used to retrieve icons as text. Usage: const fontFamily = Icon.getFontFamily()
getImageSource
Returns a promise that resolving to the source of a bitmap version of the icon for use with Image component et al. Usage: const source = await Icon.getImageSource(name, size, color)
getImageSourceSync
Same as getImageSource but synchronous. Usage: const source = Icon.getImageSourceSync(name, size, color)
getRawGlyphMap
Returns the raw glyph map of the icon set. Usage: const glyphMap = Icon.getRawGlyphMap()
hasIcon
Checks if the name is valid in current icon set. Usage: const isNameValid = Icon.hasIcon(name)
Styling
Since Icon builds on top of the Text component, most style properties will work as expected, you might find it useful to play around with these:
backgroundColor
borderWidth
borderColor
borderRadius
padding
margin
color
fontSize
NOTE: On android Text doesn't currently support border* styles, to circumvent this simply wrap your Icon with a View.
By combining some of these you can create for example :
Icon.Button Component
A convenience component for creating buttons with an icon on the left side.
Text and icon color, use iconStyle or nest a Text component if you need different colors.
white
size
Icon size.
20
iconStyle
Styles applied to the icon only, good for setting margins or a different color. Note: use iconStyle for margins or expect unstable behaviour.
{marginRight: 10}
backgroundColor
Background color of the button.
#007AFF
borderRadius
Border radius of the button, set to 0 to disable.
5
onPress
A function called when the button is pressed.
None
Usage as PNG Image/Source Object
Convenient way to plug this in into other components that rely on bitmap images rather than scalable vector icons. Takes the arguments name, size and color as described above.
Alternatively you may use the synchronous method Icon.getImageSourceSync to avoid rendering glitches. Keep in mind that this method is blocking and might incur performance penalties. Subsequent calls will use cache however.
Multi-Style Fonts
Some fonts today use multiple styles, FontAwesome 5 for example, which is supported by this library. The usage is pretty much the same as the standard Icon component:
import Icon from 'react-native-vector-icons/FontAwesome5';const myIcon1 = <Icon name="comments" size={30} color="#900" />; // Defaults to regularconst myIcon2 = <Icon name="comments" size={30} color="#900" solid />;const myIcon3 = <Icon name="comments" size={30} color="#900" light />; // Only in FA5 Pro
Static methods
All static methods from Icon is supported by multi-styled fonts.
Prop
Description
getFontFamily
Returns the font family that is currently used to retrieve icons as text. Usage: const fontFamily = Icon.getFontFamily(style)
getImageSource
Returns a promise that resolving to the source of a bitmap version of the icon for use with Image component et al. Usage: const source = await Icon.getImageSource(name, size, color)
getImageSourceSync
Same as getImageSource but synchronous. Usage: const source = Icon.getImageSourceSync(name, size, color)
getRawGlyphMap
Returns the raw glyph map of the icon set. Usage: const glyphMap = Icon.getRawGlyphMap(style)
hasIcon
Checks if the name is valid in current icon set. Usage: const isNameValid = Icon.hasIcon(name, style)
getStyledIconSet
Use this to get a Icon component for a single style. Usage. const StyledIcon = Icon.getStyledIconSet(style)
If no style argument is passed (or if it's invalid) the methods will default to a pre-defineds fallback.
Components
Icon.Button is supported, usage is just like Icon:
import Icon from 'react-native-vector-icons/FontAwesome5';const myButton = ( <Icon.Button name="facebook" onPress={this.loginWithFacebook} solid> Login with Facebook </Icon.Button>);
Custom Fonts
createIconSet(glyphMap, fontFamily[, fontFile])
Returns your own custom font based on the glyphMap where the key is the icon name and the value is either a UTF-8 character or it's character code. fontFamily is the name of the font NOT the filename. Open the font in Font Book.app or similar to learn the name. Optionally pass the third fontFile argument for android support, it should be the custom font file name.
Convenience method to create a custom font based on a fontello config file. Don't forget to import the font as described above and drop the config.json somewhere convenient in your project.
import { createIconSetFromFontello } from 'react-native-vector-icons';import fontelloConfig from './config.json';const Icon = createIconSetFromFontello(fontelloConfig);
import { createIconSetFromIcoMoon } from 'react-native-vector-icons';import icoMoonConfig from './selection.json';const Icon = createIconSetFromIcoMoon( icoMoonConfig, 'LineAwesome', 'line-awesome.ttf');
Make sure you're using the Download option in IcoMoon, and use the .json file that's included in the .zip you've downloaded. You'll also need to import the .ttf font file into your project, following the instructions above.
createMultiStyleIconSet(styles [, options])
import { createMultiStyleIconSet } from 'react-native-vector-icons';/* * This is just example code, you are free to * design your glyphmap and styles to your liking */import glyphmap from './glyphmap.json';/* * glyphmap = { * "style1": [ * "hello", * "world" * ], * "style2": [ * "foo", * "bar" * ] * } */const glyphKeys = Object.keys(glyphmap); /* ["style1", "style2"] */const options = { defaultStyle: 'style1', glyphValidator: (name, style) => glyphKeys.indexOf(name) !== -1, fallbackFamily: (name) => { for (let i = 0; i < glyphKeys.length; i++) { const style = glyphKeys[i]; if (glyphmap[style].indexOf(name) !== -1) { return style; } } /* Always return some family */ return glyphKeys[0]; }};/* * The styles object consits of keys, which will be * used as the styles later, and objects which are * used as style objects for the font. The style * should have unique characteristics for each font * in order to ensure that the right one will be * chosen. FontAwesome 5 uses font weight since * 5.7.0 in order to diffirentiate the styles but * other properties (like fontFamily) can be used. * It's just a standard RN style object. */const styles = { style1: { fontWeight: '700' }, style2: { fontWeight: '100' }};const Icon = createMultiStyleIconSet(styles, options);/* Uses default style (style1) */<Icon name={'hello'} /><Icon name={'world'} style1 />/* Default style is style1 but this will fall back to style2 */<Icon name={'foo'} />/* This will also fall back to style2 */<Icon name={'foo'} style1 />/* Regular use of style2 */<Icon name={'bar'} style2 />
option
Description
default
defaultStyle
The name of the style to be used if no style is supplied during rendering.
Object.keys(styles)[0]
fallbackFamily
Function for selecting a family if a glyph is not available. The function should accept the name of the glyph as a parameter. Returns the name if the family.
(name) => Object.keys(styles)[0]
glyphValidator
Function for validating that a glyph is available for a chosen style. It has name and style as parameters, in that order. Returns true if the glyph is valid or false if it's not.
(name, style) => true
iOS
You have to manually make a reference of your .ttf on your xcodeproj Resources folder and in Info.plist.
Animation
React Native comes with an amazing animation library called Animated. To use it with an icon, simply create an animated component with this line: const AnimatedIcon = Animated.createAnimatedComponent(Icon). You can also use the higher level animation library react-native-animatable.
Usage Examples
IconExplorer
Try the IconExplorer project in Examples/IconExplorer folder, there you can also search for any icon.
Since TabBarIOS was removed from core in favor of @react-navigation/bottom-tabs, it is also removed as a convenience component from this library. Simply use the Icon instead, but don't forget to import and link to this project as described above first.
Since ToolbarAndroid was removed from core, it is also removed as a convenience component from this library. Simply use getImageSourceSync instead, but don't forget to import and link to this project as described above first.
Make sure you've copied the font to android/app/src/main/assets/fonts.
Delete the build folder with rm -rf android/app/build.
Recompile the project.
Red screen with "Unrecognized font family" error on iOS
Make sure you've added manually the reference of your .ttf on your xcodeproj Resources folder.
Check that the font you are trying to use appears in Info.plist, if you've added the whole folder and it's blue in color, then you need to add it to the path.
Check that the font is copied in the Copy Bundle Resources in Build Phases.
Delete the build folder with rm -rf ios/build
Recompile the project.
Android build fails on Windows for no good reason
Both npm and android file hierarchies tend to get very deep and even worse when you combine them. Since Windows file system has a max length, long file name addresses will result in numerous errors including Execution failed for task ':react-native-vector-icons:processReleaseResources'. So try to keep the path to your project folder as short as possible.
Wrong icons are shown after upgrading this package
You probably didn't update the font files linked to your native project after upgrading. However, this only applies to Android targets since iOS bundles the fonts when building the app (try to clean your build from Xcode if the problem exists). On android you can relink the project or you manually update the fonts. To have them automatically synced use the gradle approach.
Some icons are missing after upgrading this package
Sometimes vendors decides to remove some icons from newer releases, this has nothing to do with this package. If you depend on an older version of a font you can add it as a custom font.
Unable to resolve module @expo/vector-icons/XXXFont
You are probably trying to use @expo/vector-icons and react-native-vector-icons at the same time. The expo package aliases this one and will take precedence. Use only one of these libraries in your project.
Web-pack complains about unsupported JSX Syntax
You will need to add JSX support for react-native-vector-icons to your transpiler configuration e.g. babel.
For example, to add react-native-vector-icons to the list of modules that support JSX (if using webpack) you may need to add the relative path to react-native-vector-icons in the include section of your JSX config.
This may look something like the following if you are using Babel in webpack:
// Process application JS with Babel. // The preset includes JSX, Flow, TypeScript, and some ESnext features. { test: /\.(js|mjs|jsx|ts|tsx)$/, include: [ paths.appSrc,+ // START - support for JSX in react-native-vector-icons+ path.resolve(+ __dirname,+ // modify this path to be relative to you webpack config,+ // "../node_modules/react-native-vector-icons", // <- most common+ "../../../node_modules/react-native-vector-icons", // <- if using workspaces+ ),+ // END - support got react-native-vector-icons ], loader: require.resolve("babel-loader"),