wix/react-native-ui-lib: a design system toolkit, not just a component pack

The problem react-native-ui-lib actually solves

Most React Native component libraries hand you a set of widgets with fixed styling. You get a Button, you get a Card, and if your designer wants the corner radius to be 8 everywhere, you either pass a prop at every call site or you wrap each component yourself. That works until the app grows and the wrappers multiply.

react-native-ui-lib approaches this from the other direction. The README describes it as a "UI Toolset & Components Library", and the toolset half is the point. You load your foundations once (colors, typography, spacings), set component defaults once, and then use the components directly. The README frames this as creating your own design system in three steps, and the third step is where the payoff shows: components accept modifiers like padding-page and marginB-s4 that resolve against the values you loaded earlier.

The audience is teams with a design function. If a designer hands you a Figma library (the README links one) and a spacing scale, this library is built to absorb that input. If you are a solo developer shipping a prototype and you want a button that looks fine, the setup cost is real overhead for no benefit.

How the foundation, theme and modifier layers connect

Three mechanisms do the work, and they run in a fixed order.

First, loaders register global values. Colors.loadColors, Typography.loadTypographies and Spacings.loadSpacings each take an object and make those keys available everywhere. The README's example registers primaryColor, secondaryColor, textColor and others, plus typographies named heading, subheading and body.

Second, ThemeManager.setComponentTheme sets per-component defaults. It accepts a plain object, as with Card and borderRadius: 8, or a function that receives props and context and returns a style object. The README's Button example uses that function form to branch on a custom prop called square, which is not an original Button prop. That detail matters: the theme function sees props you invented, so you can build variants without forking the component.

Third, modifiers resolve at render time. In the README's screen example, View takes flex and padding-page, Text takes heading and marginB-s4, Card takes padding-card, and Button takes body, bg-primaryColor and square. Each of those tokens traces back to a loader or a theme rule. So the data flow is: loaders populate a global registry, ThemeManager adds component-level defaults, and the component reads both when it renders. Change the loader value and every screen that uses the token moves with it. That is the whole argument for adopting this over a component pack.

Installing react-native-ui-lib and rendering a themed screen

The README does not inline the install commands. It points to a setup page at wix.github.io/react-native-ui-lib/docs/getting-started/setup, and it gives version guidance instead: use react-native-ui-lib for React Native >= 0.60.0, and react-native-ui-lib@^3.0.0 for anything older. The package name on npm is react-native-ui-lib.

The first real use is the three-step sequence from the README. Step one, foundations:

// FoundationConfig.js
import {Colors, Typography, Spacings} from 'react-native-ui-lib';

Colors.loadColors({
  primaryColor: '#2364AA',
  secondaryColor: '#81C3D7',
  textColor: '##221D23',
  errorColor: '#E63B2E',
  successColor: '#ADC76F',
  warnColor: '##FF963C'
});

Note that the README's own snippet has double hashes in two of the color values, textColor and warnColor. That is a typo in the documentation, not a supported format. Use single-hash hex values when you copy it.

Step two, component defaults, using the function form so you can branch on a custom prop:

// ComponentsConfig.js
import {ThemeManager} from 'react-native-ui-lib';

ThemeManager.setComponentTheme('Button', (props, context) => {
  if (props.square) {
    return {borderRadius: 0};
  }
});

Step three, a screen that consumes both layers through modifiers:

// MyScreen.js
import React, {Component} from 'react';
import {View, Text, Card, Button} from 'react-native-ui-lib';

class MyScreen extends Component {
  render() {
    return (
      <View flex padding-page>
        <Text heading marginB-s4>My Screen</Text>
        <Card height={100} center padding-card marginB-s4>
          <Text body>This is an example card </Text>
        </Card>
        <Button label="Button" body bg-primaryColor square></Button>
      </View>
    );
  }
}

What you should see is a padded screen with a heading, a card inset by the card spacing value, and a square button whose background comes from primaryColor and whose label uses the body typography. If the tokens do not resolve, the usual cause is that FoundationConfig.js was never imported before the screen rendered. The README does not show where to import it, so wiring that up is on you.

The New Architecture gap is the constraint to plan around

The README's Notes section is unusually direct about this. The library is being upgraded to support the new React Native Architecture, it currently supports React Native 0.73, and the plan is to support React Native 0.77 next. The README states there is no timeline yet and calls it part of the roadmap.

Read that as a hard constraint, not a footnote. If your app is already on a React Native version past 0.73, or if you are planning a migration to the new architecture this quarter, this library is the wrong tool right now, because the support statement is a version ceiling rather than a compatibility range. The version guidance in the README (>= 0.60.0 for the current package, ^3.0.0 below that) tells you which package to install; the Notes section tells you how far forward you can go.

The second limitation is structural. Because components read from a global registry, a theme change is a global change. That is the feature, but it also means a screen that needs to deviate from the loaded foundations has to fight the system rather than work with it. The ThemeManager function form mitigates this per component, and the README shows exactly that pattern, but there is no documented scoping mechanism for applying a different set of foundations to a subtree. The README does not document one, so plan on a single global theme.

react-native-ui-lib compared with React Native Paper and UI Kitten

The search data around this library is dominated by comparisons, and the comparison is a real one. React Native Paper and React Native UI Kitten are the two names that come up most often alongside it.

The difference is where the theming lives. React Native Paper centers on Material Design, so its defaults encode a specific visual language and you adjust within it. UI Kitten ships a theme system built around named themes and an Eva Design specification, which gives you a structured way to swap between light and dark variants. react-native-ui-lib starts with no visual language at all: you load colors, typography and spacings, and the components are neutral until you do. The README's three-step framing is the clearest statement of that position.

That makes the choice fairly clean. If you want Material components that look like Material, Paper gets you there faster. If you want a design system that matches a Figma file your team already maintains, react-native-ui-lib asks for the config work up front and then keeps every component in sync with it. If your team has no design specification to encode, the library's main advantage does not apply to you.

Maintenance cadence, licence and upgrade cost

The repository is not archived and the last push was on 2026-06-28, which is under three months before today's date, so the project is being worked on. The most recent release listed is [email protected] on the same date, with 8.5.1 and 9.0.2 landing on 2026-05-24. That is a steady release rhythm through the first half of 2026.

The version history is the upgrade-cost signal. The README documents a "New Major Version 6.0" with a dedicated breaking-changes page, and the release list shows the project has since moved through 8.x and into 9.x. Major versions here are not cosmetic. Treat a major bump as a migration task with a changelog read, not a dependency bump.

The licence is MIT, stated in both the README metadata and the root package.json. MIT is permissive: it allows commercial use and modification, and it requires that the copyright notice and licence text be preserved in distributions. That is a summary of what the licence identifier means, not legal advice for your situation. The root package.json marks the repository itself as private, which is normal for a monorepo root; the published package is react-native-ui-lib under MIT.

Editorial conclusion

Adopt react-native-ui-lib if you are building a product where a shared design system matters more than picking up components one at a time, and if your app can sit on React Native 0.73 while the New Architecture work lands. Do not adopt it if you need the new architecture today or you want components that work with no configuration step. Before committing, verify two things yourself: that your React Native version matches the 0.73 line the README states, and that your team is willing to own FoundationConfig.js and ComponentsConfig.js, since every component you use will inherit whatever those files say.

Frequently asked questions

Official sources

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