react-native-ui-lib: A Design System Toolkit That Puts Theme Configuration First

The Problem It Solves and Who It Targets

React Native apps lack a standard way to define and reuse visual foundations. Each team ends up writing its own color constants, typography scales, and spacing values, then wiring them into every component by hand. react-native-ui-lib attacks that by packaging a full component set with a theming layer that sits above it. The intended user is a team building a product UI, not a library author. Wix built it for its own mobile apps, and the public release carries that internal-tool pragmatism. The README frames it as a "UI Toolset & Components Library," which is honest: you get both the components and the configuration system, and the two are designed to work together.

The Three-Step Theming Mechanism

The core workflow is explicit and short. Step one loads foundations through three objects: Colors, Typography, and Spacings. Each has a load method that takes a plain JavaScript object. For example, Colors.loadColors accepts hex values, Typography.loadTypographies takes fontSize and fontWeight pairs, and Spacings.loadSpacings maps names like 'page' or 'card' to pixel values. Step two sets component defaults through ThemeManager.setComponentTheme. That method accepts either a plain object, which applies to all instances, or a function that receives props and context. The function form lets you branch on custom props, as the README shows with 'square' on a Button. Step three is using the components with modifiers, which are shorthand props like flex, padding-page, or bg-primaryColor. The whole system is declarative and centralized, which is a real advantage over scattering styles across files.

Getting It Running: Installation and Version Constraints

The README points to a setup guide on the docs site rather than listing commands inline. What it does state clearly is the version split: for React Native 0.60 and above, use the current package name react-native-ui-lib. For anything below 0.60, you must pin to react-native-ui-lib@^3.0.0. That is a hard boundary, and it matters for legacy projects. The current release line, 9.1.0, was pushed in June 2026. The README also flags a new major version 6.0 with a dedicated breaking changes page. If you are coming from an older major, you cannot just bump the version and expect the same API. The installation itself is a standard npm package, but the real setup cost is in the configuration files you create, like FoundationConfig.js and ComponentsConfig.js, which the README shows as separate modules.

New Architecture Status and a Real Limitation

The README's most notable limitation is the React Native New Architecture support. It says, in the "Notes" section, that the team is "working on upgrading our UI Library to support the new React Native Architecture." Currently the library supports React Native 0.73, and the next planned target is 0.77. There is no timeline. For a team starting a new project today, that means you are locked to an older React Native version if you want this library. That is a genuine constraint, not a hypothetical one. The New Architecture changes how native modules and components are bridged, so any library that has not migrated will either break or force you to use the legacy interop layer. If your project must run on 0.77 or later, this library is the wrong tool right now. The README does not say when 0.77 support will land, so you cannot plan around a date.

The Alternative: Build Your Own Theming or Use a Different Library

The obvious alternative is to not use this library and instead assemble your own theming with React Native's built-in StyleSheet and a context provider. That approach gives you full control over the API and no dependency on Wix's release cadence. The difference is that you have to write the modifier system yourself. Modifiers like flex or padding-card are not part of core React Native; they are a convenience layer that this library provides. The trade-off is clear: adopting react-native-ui-lib buys you a ready-made modifier grammar and a set of themed components, but it ties you to the library's versioning and its React Native support window. Another alternative is a different component library, but the README does not name any, so any comparison would be speculation. The concrete difference here is between a prebuilt system and a hand-rolled one, and the decision hinges on whether you value speed of setup over independence.

Maintenance and Upgrade Cost

The maintenance burden is visible in the repository activity. The last push was June 2026, and there are three recent releases clustered around May and June 2026, including a jump from 8.5.1 to 9.0.2 and then 9.1.0. That suggests active development, but it also means you will need to track minor and major releases. The v6 breaking changes page exists precisely because upgrades are not painless. The README does not document a migration path beyond pointing to that page, so you should expect to read release notes and adjust your configuration files. The license is MIT, which is permissive and imposes no copy-left obligations, but it also means there is no commercial support contract. You are relying on Wix's OSS team and community through the Discord channel. For a production app, budget time for testing each upgrade, especially across major versions.

Editorial conclusion

Adopt react-native-ui-lib if you want a prebuilt component set with a centralized theming model and you can stay on React Native 0.73 for now. Skip it if you must use React Native 0.77 or the New Architecture immediately, because the library does not support either yet. Before committing, verify that your project's React Native version matches the 0.73 requirement and check the v6 breaking changes guide, since the upgrade path from older versions is not automatic.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes