gluestack-ui v5: copy-paste React Native components built on NativeWind

The problem gluestack-ui solves for React Native teams

Most React Native component libraries arrive as a package you import. You get the maintainer's markup, the maintainer's styling decisions, and a version number you bump when they ship. Changing a default padding means either wrapping the component or forking the library.

gluestack-ui takes the opposite route. The README states that it is "not a pre-packaged dependency" and that you "choose the components you need and copy-paste them directly into your Expo and React Native projects." The component source lands in your repository. You edit it like your own code, because it is your own code.

That trade is aimed at a specific reader: a team building an Expo app that already uses NativeWind for styling, wants Tailwind-style utility classes on native views, and has been burned by fighting a library's internal styles. It is less useful if you want a dependency you can update without touching application files.

The v5 release notes describe support for NativeWind v5 (Tailwind v4), an optimized CLI, Expo Router first, and native components. Those are the claims the project makes about this version; the README does not quantify any of them.

How the copy-paste model works with NativeWind

The mechanism is a CLI plus a set of component templates. The repository is a monorepo: package.json at the root is private, and the layout includes packages/, apps/, docs/ and scripts/. The root scripts drive development across those workspaces, with entries such as dev:kitchen-sink, dev:website and sync:starter-kits calling scripts/dev.ts with a --mapper flag.

For a consumer, the flow is simpler than the repository suggests. You run the CLI inside an existing Expo or React Native project. It writes component files into your source tree. Those files are styled with NativeWind classes, so your Tailwind configuration and theming tokens decide how they render. The README lists theming tokens and configuration as the customization path, and describes accessibility as a built-in property of the components.

Because the components are local, there is no runtime package resolving styles on your behalf. The consequence is that upgrades are not a version bump. When v5 changed its styling foundation to NativeWind v5 and Tailwind v4, existing copied components would not pick that up automatically. The README handles this with a migration guide link for v3 and v4 users, and says nothing about an automated codemod.

Installing gluestack-ui v5 and adding a first component

The README is explicit that you need an existing Expo or React Native project first. There is no standalone starter in the installation section. The command it gives is:

npx gluestack-ui init

Running that inside your project is the documented entry point. For the full set of prompts and options, the README points to the v5 installation guide on gluestack.io rather than listing flags, so treat the CLI's own output as the source of truth for what it asks.

After initialization, the README says you add components either through the CLI or by copying from the documentation. It does not print the add command in the README, so check the installation guide for the exact subcommand before scripting it in CI. Once a component file is in your project, you import it by its local path, not from a gluestack package, and style it with NativeWind classes.

The root package.json shows how the maintainers run the same codebase locally, which is useful context if you plan to contribute rather than consume:

yarn dev:kitchen-sink
yarn sync:starter-kits

Those scripts are for the monorepo itself. A consumer project does not need them.

What you give up when the components live in your repo

Copy-paste libraries move maintenance cost from the publisher to you. If a component has an accessibility bug, you either patch your copy or re-copy the fixed version and reapply your edits. The README lists accessibility as a feature, but the README does not describe how fixes reach projects that already copied a component.

The version history makes the cost concrete. v4.0.0-alpha appeared on 2026-01-28, v5.0.0-alpha.0 on 2026-03-16, and v5.0.0 on 2026-06-25. A project that copied components during the alpha period has no automatic path to the stable release; the README directs migration questions to the documentation site.

There is also a coupling constraint. The v5 release is built around NativeWind v5 and Tailwind v4. If your app is on an older NativeWind line, or you style with styled-components, adopting v5 components means adopting that styling stack or rewriting the class names in every copied file. The topics list includes styled-components, but the README's stated stack is TypeScript, React Native, Expo, Tailwind CSS and NativeWind.

Finally, the README does not document rollback. If initialization writes files you do not want, the README gives no uninstall or revert procedure, so version control is your safety net.

gluestack-ui compared with Tamagui and React Native Paper

The difference between these options is mostly about where the component code lives and what controls styling.

React Native Paper is a conventional dependency. You install a package, import components, and theme through its provider API. You do not see or edit component internals. Upgrades are version bumps, and your styling is expressed in Paper's theming system rather than utility classes.

Tamagui also ships as a package and centers on its own compiler and styling system, with a strong emphasis on cross-platform output and optimization. You configure it through its own config file and tokens. Like Paper, the component code is not yours to edit in place.

gluestack-ui v5 sits closer to the shadcn model that React web developers know: source in your tree, styling through Tailwind utilities via NativeWind, and a CLI that writes files. If your team already thinks in Tailwind classes and wants to own the markup, that model is coherent. If your team prefers a versioned dependency with a documented theme API, Paper or Tamagui fit that expectation better.

The README does not contain a feature-by-feature comparison with any of these, so treat the choice as a workflow decision: who edits the component, and who owns the upgrade.

Licence and the cost of staying current

The README states the project is licensed under the MIT License, Copyright © 2026 GeekyAnts, and links to the LICENSE file. MIT is permissive: you can use, modify and redistribute the components, including the copies the CLI writes into your project. This is not legal advice; read the LICENSE file and your own counsel's guidance for your situation.

The practical licence consequence of the copy-paste model is that once components are in your repository, they are your code under your project's terms. Attribution requirements are whatever MIT requires for the portions you keep, and the README does not add a separate commercial restriction. It also does not describe a paid tier, so nothing in the README suggests a licence gate on the components themselves.

Upgrade cost is the real recurring expense. The repository was last pushed on 2026-09-02, and v5.0.0 shipped on 2026-06-25. There is no documented mechanism for pulling upstream component fixes into an existing copy. Budget for re-reading the migration guide at each major version, and for re-copying components whose class names changed when the NativeWind foundation moved.

Editorial conclusion

gluestack-ui v5 suits teams already on Expo and NativeWind who want component source in their own repository and are willing to own upgrades of that copied code. It is a poor fit if you want a single versioned package you can bump in package.json, or if you are not using NativeWind at all. Before adopting, run npx gluestack-ui init on a branch and read exactly which files it writes, then check the v5 migration guide for what changed from v3 and v4, because the README points there rather than describing the steps.

Frequently asked questions

Official sources

1. gluestack/gluestack-ui on GitHub
2. Issues
3. Project website
4. README
5. Releases