Repository: oblador/react-native-vector-icons

Stars: 17846

README.md Copy Chapter

!Vector Icons for React Native

 

React Native Vector Icons

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.

For the integration of .svg files natively, you can explore react-native-vector-image.

Table of Contents Copy Chapter

- Sponsorship
- Available Icon Sets
- Installation
- Setup
- Icon Component
- Usage as PNG Image/Source Object
- Multi-Style Fonts
- Custom Fonts
- Animation
- Dynamic icon font loading
- Usage Examples
- Changelog
- License

Sponsorship Copy Chapter

Should you find this library beneficial, kindly contemplate the option of
sponsoring.

Available Icon Sets Copy Chapter

Explore all icons.

RNVI comes with the following supported icons. You can search NPM for third party icons.

Actively maintained Copy Section

- AntDesign from Ant Group (v4.4.2 with _449_ icons)
- Feather created by Cole Bemis & Contributors (v4.29.2 featuring _287_ icons)
- FontAwesome designed by Fonticons, Inc. (v7.2.0 featuring _2,806_ free and _75,767_ pro icons)
- Foundation by ZURB, Inc. (v3.0 with _283_ icons)
- Ionicons crafted by Ionic (v8.0.9 containing _1,357_ icons)
- MaterialDesignIcons from MaterialDesignIcons.com (v7.4.47 including _7448_ icons)
- Octicons designed by GitHub, Inc. (v19.23.1 with _370_ icons)
- Lucide designed by Lucide, (v1.7.0 with _1,941_ icons)

No longer maintained upstream Copy Section

- Entypo by Daniel Bruce (v1.0.1 with _411_ icons)
- EvilIcons designed by Alexander Madyankin & Roman Shamin (v1.10.1 with _70_ icons)
- FontAwesome 4 by Fonticons, Inc. (v4.7.0 containing _785_ icons)
- FontAwesome 5 from Fonticons, Inc. (v5.15.4 offering _1611_ free and _7869_ pro icons)
- FontAwesome 6 designed by Fonticons, Inc. (v6.7.2 featuring _2060_ free and _52663_ pro icons)
- Fontisto created by Kenan Gündoğan (v3.0.4 featuring _617_ icons)
- MaterialIcons by Google, Inc. (v4.0.0 featuring _2234_ icons)
- SimpleLineIcons crafted by Sabbir & Contributors (v2.5.5 with _189_ icons)
- Zocial by Sam Collins (v1.1.1 with _100_ icons)

Migration Copy Chapter

See MIGRATION.md if you are migrating from react-native-vector-icons to the package-per-icon-set approach or between major versions.

Installation Copy Chapter

1. Install the packages for the icons you want to use

npm install @react-native-vector-icons/fontawesome-free-solid @react-native-vector-icons/evil-icons

2. Depending on the platform you're targeting (iOS/Android/Windows), follow the appropriate setup instructions below.
3. If you are using one of the following fonts, refer to their guides for further instructions

- Fontello
- Icomoon

Setup Copy Chapter

Refer to the guide for Expo, React Native or Web for further instructions.

Font location customisation Copy Section

For fonts like the FontAwesome Pro as well as Fontello and Icomoon where you provide the fonts, the default location for the font files is rnvi-fonts in the same directory as your package.json. This can be customized by setting the fontDir property in your package.json file.

{
  "reactNativeVectorIcons": {
    "fontDir": "src/rnvi-fonts"
  }
}

Icon Component Icon Component')" title="Copy chapter prompt for LLMs"> Copy Chapter

You can either use one of the bundled icons above or roll your own custom font.

import { FontAwesomeFreeSolid } from "@react-native-vector-icons/fontawesome-free-solid";
// or use the static version to embed the font at build time instead of loading it at runtime
import { FontAwesomeFreeSolid } from "@react-native-vector-icons/fontawesome-free-solid/static";
<FontAwesomeFreeSolid name="rocket" size={30} color="#900" />;

Props Copy Section

Any Text props and the following:

| Prop | Description | Default |
| ----------- | ----------------------------------------------------------------------- | ----------- |
| size | 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_ |

Styling Copy Section

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

By combining some of these you can create for example :

!type
!star

Usage as PNG Image/Source Object Copy Chapter

Convenient way to plug this in into other components that rely on bitmap images rather than scalable vector icons.

You need to use Expo (with expo-font installed) _or_ install @react-native-vector-icons/get-image to use this feature.

Both methods return an ImageResult object ({ uri, width, height, scale }) that can be passed directly as an Image source.

const source = Icon.getImageSourceSync('user', 20, 'red');
// or with an options object:
const source = Icon.getImageSourceSync('user', { size: 20, color: 'red', lineHeight: 28 });
return <Image source={source} />;

Alternatively you may use the async method Icon.getImageSource.

const source = await Icon.getImageSource('user', 20, 'red');
// or with an options object:
const source = await Icon.getImageSource('user', { size: 20, color: 'red' });

Keep in mind that Icon.getImageSourceSync is blocking and might incur performance penalties. Subsequent calls will use cache, however.

Static methods Copy Section

All static methods from Icon are supported by multi-styled fonts.

| Method | Description |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| getImageSource | Returns a promise resolving to an ImageResult of a bitmap version of the icon. Usage: const source = await Icon.getImageSource(name, { size, color, lineHeight }) |
| getImageSourceSync | Same as getImageSource but synchronous. Usage: const source = Icon.getImageSourceSync(name, { size, color, lineHeight }) |

Custom Fonts Copy Chapter

The best approach is to use our icon generator to create your own icon package.

See CREATE_FONT_PACKAGE.md to learn how to create your own font packages.

You can also use createIconSet() directly in your project. This
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 its character code.
postScriptName is the name of the postscript font. Open the font in <https://fontdrop.info/>,
Font Book.app or similar to learn the name. Also pass the fontFileName argument for Android support.

import { createIconSet } from "@react-native-vector-icons/common";
const glyphMap = { "icon-name": 1234, test: "∆" };
// use createIconSet() with object parameter
// or use positional parameters for compatibility with version <= 10: createIconSet(glyphMap, fontFamily[, fontFile])
const Icon = createIconSet(glyphMap, {
  postScriptName: "FontName",
  fontFileName: "font-name.ttf",
  fontSource: require("../fonts/font-name.ttf"), // optional, for dynamic loading. Can also be a local file uri.
});

If you aren't using dynamic font loading you need to make sure your font is copied into your bundle.

Animation Copy Chapter

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.

Dynamic icon font loading Copy Chapter

TL;DR we recommend you use the /static import if you use Development builds and the root import when using Expo Go.

Icon fonts can be made available statically at build time or loaded dynamically at runtime. The root (non-/static) import uses dynamic loading. If you don't need dynamic loading, use the /static imports (e.g. "@react-native-vector-icons/ionicons/static").

See the Expo setup guide for more details, config plugins, and the dynamic loading API.

Usage Examples Copy Chapter

Icon Explorer Copy Section

Try the IconExplorer project in Examples/IconExplorer folder, there you can also search for any icon.

!Screenshot of IconExplorer

Basic Example Copy Section

import { IonIcons } from "@react-native-vector-icons/ionicons/static";
const ExampleView = () => (
  <IonIcons name="ios-person" size={30} color="#4F8EF7" />
);

Inline Icons Copy Section

import { Text } from "react-native";
import { IonIcons } from "@react-native-vector-icons/ionicons/static";
const ExampleView = (props) => (
  <Text>
    Lorem <IonIcons name="ios-book" color="#4F8EF7" /> Ipsum
  </Text>
);

Testing Copy Chapter

When running tests with jest you will need to mock out the native code loading to prevent errors.

In jest.config.js add

// Mock out font loading
moduleNameMapper: {
  '\\.(ttf)$': '<rootDir>/__mocks__/file-mock.js',
}

Create __mocks__/file-mock.js:

module.exports = {};

Create __mocks__/@react-native-vector-icons/common.js:

// Mock the entire common library so there are no native module loading errors
module.exports = {
  createIconSet: () => "icon",
};

Changelog Changelog')" title="Copy chapter prompt for LLMs"> Copy Chapter

License Copy Chapter

This project is licenced under the MIT License.

Any bundled fonts are copyright to their respective authors and mostly under MIT or SIL OFL.