Note: gluestack-ui v5 does not currently support Next.js. Next.js support will be available as soon as NativeWind v5 adds web support. For Next.js projects, refer to the

v4 documentation

Step 1: Initialize

Run the following command at the root of your project:

npx gluestack-ui@alpha init

The CLI prompts you to select a styling engine:

NativeWind v5 — Expo & React Native CLI, powered by Tailwind CSS v4 + PostCSS

UniWind — Expo-only, powered by Tailwind CSS v4 with no PostCSS build step

Step 2: Add components

npx gluestack-ui@alpha add button

See the

CLI guide

for all available commands and options.

Common Issues

Expo app stuck in
tailwindcss(ios) rebuilding...
while running
expo start
Your project directory name may contain spaces (e.g.

Expo App

). Rename it to remove spaces (e.g.

Expo-App

). Peer dependency resolution errors Use the

--legacy-peer-deps

flag:

npm install --legacy-peer-deps

NativeWind v5 build errors related to lightningcss Ensure

lightningcss

is pinned to

1.30.1

in both

overrides

and

resolutions

package.json

, then run a clean install. UniWind theme tokens not applying on web Ensure

.light {}

and

.dark {}

are at the top level of

@layer theme

— not nested inside

:root {}

. Nesting them inside

:root {}

causes the selectors to be treated as descendants of

:root

rather than being applied to

:root

itself.

Edit this page on GitHub