react-native-vector-icons: one npm package per icon set, and what that change cost

Why the single package was split up

The change that defines the current state of this project is structural. Instead of one `react-native-vector-icons` package containing every icon font, there is now one package per icon set, named by family, and you install only the ones you use. The README says this explicitly to anyone still on the old package: the 10.x branch remains available as a separate tree, and `MIGRATION.md` is the document for moving to the package-per-icon-set approach.

The reasoning is straightforward and the payoff is bundle size. An app that draws three icons from one family previously linked the fonts for all of them, and with font files that is not a rounding error on mobile. Splitting the packages means an unused family never enters the build.

The practical consequence is that the install line names the packages explicitly:

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

Two packages there, chosen by the app. Each publishes its own version, so a project can be on MaterialDesignIcons 13.x while Lucide sits at an earlier major. That is the mechanism that enables tree shaking, and it is also the thing that makes version bookkeeping your problem.

Reading the icon table as a maintenance report

The most useful content in this README is a table of icon sets split into two lists, and the split is the interesting part. One list is headed as actively maintained and the other as no longer maintained upstream, which is a distinction the project makes about other people's font libraries rather than about its own code.

In the maintained list, versions are current as of the README: MaterialDesignIcons at v7.4.47 with 7,448 icons, FontAwesome at v7.2.0, Ionicons at v8.0.9 with 1,357 icons, Octicons at v19.23.1, Lucide at v1.7.0 with 1,941 icons, AntDesign at v4.4.2 with 449 icons, Feather at v4.29.2 with 287 icons, and Foundation at v3.0 with 283 icons.

The second list is where a reader should slow down. MaterialIcons is pinned at v4.0.0, SimpleLineIcons at v2.5.5, Entypo at v1.0.1, Zocial at v1.1.1, Fontisto at v3.0.4, EvilIcons at v1.10.1, and three separate frozen FontAwesome generations at v4.7.0, v5.15.4 and v6.7.2. A version of 1.0.1 or 1.1.1 on a library with years of history is the tell: the font is not going to gain glyphs, and if your design needs one, nobody upstream is adding it.

So the table is effectively a risk register. Bundling FontAwesome 4 alongside FontAwesome 6 is technically supported here, and practically odd, because you have three generations of the same icon family in one app.

The Icon component and the static import option

Usage is a named import per set, and the README shows an alternative worth understanding:

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" />;

The regular import loads the font at runtime, which means a brief period where the glyph is invisible or falls back. The `static` import embeds the font at build time, trading binary size for a guaranteed first paint. Both give you the same component, and the choice is per import path rather than per project.

The component builds on React Native's `Text`, and the README is explicit that any Text prop works, with three additions: `size`, defaulting to `12`, which can also be passed as `fontSize` in a style object; `name`, which selects the glyph; and `color`, which is inherited when unset. Because it is a `Text` underneath, `backgroundColor`, `borderWidth`, `borderColor`, `borderRadius`, `padding`, `margin`, `color` and `fontSize` all apply, which is what makes badges and buttons straightforward rather than requiring nested wrapper views.

The default size of 12 is small enough to surprise people. If you omit `size`, your icon renders at 12 pixels regardless of surrounding text.

Platform setup is delegated to three separate guides

The README's installation section is short on purpose. After the install line it says to follow the setup instructions for your platform, and points at three files in the repository: `docs/SETUP-EXPO.md`, `docs/SETUP-REACT-NATIVE.md` and `docs/SETUP-WEB.md`. Anything beyond that, including per-platform font linking, is in those files rather than on the front page.

Two font families need extra steps of their own, and the README lists them with links to their own package READMEs: Fontello and Icomoon. Both are cases where you supply the font files yourself, which leads to the configuration option.

For fonts you provide, including FontAwesome Pro as well as Fontello and Icomoon, the default location for the font files is `rnvi-fonts` next to your `package.json`, and `fontDir` changes it:

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

That is a small but important detail, because a project that keeps fonts outside the package root will fail to bundle them without it.

The repository also links `react-native-vector-image` for `.svg` files natively, which is a separate project. If you want arbitrary SVG rather than an icon font, this library is the wrong tool and that link is the redirect.

A monorepo with generated packages and per-package releases

The repository layout explains how the packages are produced and why the release log looks the way it does. There is a `packages/` directory holding each icon set, an `apps/` directory, a `scripts/` directory with a `generate-fonts.sh` script, and `nx.json` plus `pnpm-workspace.yaml` at the root. The manifest is private with version `0.0.1`, which is the conventional placeholder for a workspace root that is never itself published, and it pins `[email protected]` and requires Node `>= 22.0.0`.

The scripts section shows the workflow: `generate` runs the font generation script, and `clean`, `prepare` and `test` are all Nx run-many calls, meaning each package gets its own task graph. Release is `nx release`, so versioning is per package rather than for the repository as a whole.

The release history shows exactly that. The three most recent releases are `@react-native-vector-icons/[email protected]`, `@react-native-vector-icons/[email protected]` and `@react-native-vector-icons/[email protected]`, all published on 2026-09-07. Note the divergence: the SimpleLineIcons package is at 13.1.4 while Octicons is at 21.1.4, because each tracks its own font's history. All three carry the same fix, skipping an explicit Kotlin plugin when the Android Gradle Plugin already registers the kotlin extension, and all three note an update of the shared `@react-native-vector-icons/common` package to 13.0.3.

That shared `common` package is the piece to watch on upgrades. It sits underneath every icon package, so a change there affects all of them, and the fact that the last push was on 2026-09-07 with releases the same day suggests the project is actively coordinated.

When a font library is the wrong choice

There is a category of project this library should not be used for, and the README names it by omission. Icons as a font means one file per family, loaded and registered with the platform, with every glyph present in the binary whether or not you draw it. That model is excellent for a fixed, curated set of interface icons, which is exactly what this project provides, and it is poor for artwork.

If you need a handful of brand logos or illustrations that change with your design system, a font is the wrong container. The README's own redirect for arbitrary `.svg` points to `react-native-vector-image`, which treats them as images rather than glyphs. That is the right call for anything that is not an interface icon.

The deprecation question behind some of these searches has a second dimension. If you are on Expo, the project's own guidance is the `docs/SETUP-EXPO.md` guide and the README acknowledges Expo explicitly in its setup links, so this library remains supported on Expo rather than being replaced by it. What has been replaced is the single package, not the approach.

The other real cost is maintenance of the pinned versions. With one package per set and independent release trains, a project using four icon families has four version lines to track, and each one can pull a different major of the shared `common` package. Pinning explicitly, and reading the per-package release notes rather than the repository's, is the habit this structure demands.

Editorial conclusion

The package-per-icon-set structure is the right call for tree shaking, and it costs you an install step per icon family and a migration if your app still imports from the old single package. Judge this project by the upstream table in the README rather than by its own release log: several bundled icon sets are labelled as no longer maintained upstream and are frozen at versions as old as Entypo 1.0.1, so depending on them means owning that font. Start from `MIGRATION.md` if you are moving off the 10.x package, verify your platform's setup file under `docs/` before wiring fonts, and pin the versions of any set whose upstream you do not control.

Frequently asked questions

Official sources

1. License: MIT
2. oblador/react-native-vector-icons on GitHub
3. Project website
4. README
5. Releases