HeroUI Native: a React Native design system that refuses outside components

A separate package for the native side of HeroUI

The naming here confuses people at first. HeroUI began as a web component library, and `heroui-inc/heroui-native` is a distinct repository with a distinct npm package rather than a build target inside the web one. The README is short enough to read in a minute, and most of it is links: to the quick start page, to the full documentation, to a Featurebase roadmap, to the Discord, and to a separate `heroui-native-example` repository.

The badges give the useful facts. The npm package is `heroui-native`, the version in the README matches the latest release at v1.0.10, and the licence is Apache 2.0. The repository is TypeScript, its primary language, and the topics list covers android, expo, nativewind, design-system and ui-components.

There is also a preview app on the App Store, described as the official way to explore components and their variants on a device, with an Android version listed as coming soon to Google Play. That preview app is the fastest way to form an opinion about the visual style before wiring anything up.

What package.json says gets published

Because the README defers documentation to the website, `package.json` is the most informative file in the repository. It shows a package built with React Native Builder Bob, shipping compiled output alongside TypeScript declarations and the original source.

"main": "./lib/module/index.js",
"types": "./lib/typescript/src/index.d.ts",
"source": "./src/index.tsx",

The exports map is more interesting than the entry points, because it treats styles as a public surface rather than an implementation detail. Consumers get both a default stylesheet and a separate vibrant theme file.

"exports": {
    ".": {
      "source": "./src/index.tsx",
      "types": "./lib/typescript/src/index.d.ts",
      "default": "./lib/module/index.js"
    },
    "./styles": "./lib/module/styles/index.css",

The scripts tell you what the maintainers expect of a contributor: `jest` for tests, `bash ./scripts/typecheck.sh` for types, `eslint` across `src` and `example/src`, and `bob build` wired to `prepare`. There is also a `release` script running `bumpp` and a `changelog` script using `conventional-changelog` with the angular preset, which is why the release notes read as conventional commits rather than marketing prose.

The example app is the actual quick start

The README recommends the example app for anyone who wants to start building immediately, and calls it a standalone app that is fully configured and ready to use. The `heroui-inc/heroui-native-example` repository is described as containing all necessary dependencies, a Uniwind configuration, and example components showing recommended patterns, with the pitch that you can clone it and start building.

That is a different philosophy from a documentation site with copy and paste snippets. It assumes the fastest path to a working result is a project someone else already configured, which is a defensible call for a styling layer where getting the build pipeline right is half the work.

The main repository reinforces that arrangement. Its tree contains `example/` with its own `app.json`, `babel.config.js`, `metro.config.js`, `package.json`, `lingui.config.ts`, `themes/` and `global.css`, alongside the published `src/`. There is also a `docs/` directory and `lefthook.yml` for git hooks, which suggests the documentation site is built from inside this repository even though the README links to the hosted version.

Right-to-left support arrived component by component

Release 1.0.8, published on 2026-07-31, is the most instructive of the three recent releases because it shows how features land. The notes list scoped right-to-left layout support, right-to-left support across components, an extension of that work to the remaining components, and a newly exported `useIsRTL` hook. Localisation for English, Arabic and Hebrew went into the example app in the same release, along with a fix for premature flex wrapping in right-to-left mode.

Release 1.0.9 on 2026-08-31 is mostly fixes: a single `role=radio` node when nested in a group, padding applied only to composed slots, content-fit label sizing preserved, and dialog presentation on React Native Gesture Handler 3.

Release 1.0.10 on 2026-09-21 follows the same shape, with type assertions on Input and TextArea refs, better handling of dismissed state during container resize, outside taps passing through animated wrappers, and anchors refreshing when the app window changes. Read together, these notes describe a library in its first few months of hardening: a monthly cadence, small focused fixes, and visible work on the kind of platform edge cases that only appear on real devices.

Only the core team can add a component

The contributing section is the most opinionated text in the README and worth reading before you plan an extension. Bug fixes are invited through GitHub issues. Feature proposals are expected to start as a discussion in GitHub Discussions before implementation. New components are a different matter: only the core team can add them, and the roadmap is the place to check what is planned.

The README asks contributors not to add new components or variants, change existing designs, or modify component behaviour without prior discussion, and gives the reason: the project follows a strict design system based on Figma designs and the roadmap.

This is a defensible position for a brand-driven design system, and it is a real constraint for everyone else. If you need a component that does not exist, you are not extending the library, you are wrapping it or forking it. That is a materially different relationship with a dependency than what most component libraries offer, and it is worth knowing before you adopt one.

What heroui.com has to answer that the README does not

Be clear about the split before you evaluate this library. The README establishes what the project is, where the documentation lives, that a preview app exists, that an example app exists, how contributions are governed, and that the licence is Apache 2.0. It contains no installation command, no component API, no theming instructions and no migration notes.

All of that is on heroui.com under the native documentation, starting from the getting started and quick start pages. That is a reasonable arrangement for a component library whose API surface is large, and it is also why this repository is worth reading as a source of truth about packaging rather than usage. Between `package.json`, the release notes and the example app, you can answer most questions about what ships and how it is built without leaving GitHub.

The version number is the other thing to keep an eye on. At v1.0.10 the package is young, the API is still moving between patch releases, and the Android distribution of the preview app does not exist yet.

Editorial conclusion

HeroUI Native is a sensible choice if you already know the HeroUI visual language and want the same components on a phone, and a poor one if you expect a component library you can extend. The package is small and conventional: `heroui-native` on npm, version 1.0.10, built with `bob`, tested with Jest, styled through Uniwind, and published roughly monthly from a repository whose last push was on 2026-09-21. What makes it unusual is governance rather than code, since new components are a core team decision and Figma designs lead. The README will not tell you how any of that works: installation, component APIs and theming all live on heroui.com, so start with the quick start page, then read `package.json` for what actually gets published and the example app for what a configured project looks like.

Frequently asked questions

Official sources

1. heroui-inc/heroui-native on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases