gluestack-ui v4 introduces significant improvements to the animation system, performance optimizations, and enhanced compatibility with the latest React Native ecosystem. Building on the solid foundation of v3, v4 brings a modern animation engine and better developer experience.

What's New in v4

shadcn-Inspired Color System: Modern color token system with semantic naming (primary, secondary, accent, muted, etc.)

New Animation Engine: Migration from

@legendapp/motion

react-native-reanimated

(~4.2.1) for most animated components

Enhanced Performance: Better performance with the new animation system and worklets support

Tailwind v4 Support: Full compatibility with Tailwind CSS v4 (via Uniwind)

Modern Dependencies: Updated to latest React Native ecosystem packages

Improved Type Safety: Enhanced TypeScript support with better type definitions

Better Web Support: Enhanced Next.js adapter with improved SSR capabilities

Migration from v3 to v4

What's Changed:

gluestack-ui v4 introduces important dependency, configuration, and theming changes:

Color Token System: ⚠️ Breaking Change - Migrated to shadcn-like color tokens

New color naming convention (e.g.,

primary

secondary

accent

muted

, etc.)

Updates required in

tailwind.config.js

and

gluestack-ui-provider/config.ts

All component styles updated to use new tokens

Animation System: Most components now use

react-native-reanimated

instead of

@legendapp/motion

Component Styles: ⚠️ Breaking Change - All components have updated styles

Components use new color tokens

Animation library changes in some components

Must re-copy components from CLI using

npx gluestack-ui add <component>

New Dependencies: Added

react-native-worklets

react-native-reanimated@~4.2.1

, updated other packages

Babel Configuration: Required babel plugin for worklets support (Expo/RN CLI)

Package Versions: Updated to v4 alpha packages

Next.js Adapter: Updated

@gluestack/ui-next-adapter

to v4

What Stays the Same:

Component APIs remain exactly the same

Import patterns are unchanged (v3 and v4 use identical imports)

Copy-paste philosophy maintained

Overall theming approach stays the same (only token names changed)

Migration Benefits

Automatic CLI Upgrade: Simple upgrade process with

npx gluestack-ui upgrade

command

Modern Color System: shadcn-like color tokens for better theming consistency

Semantic Color Naming: More intuitive color names (primary, secondary, accent, muted, etc.)

Better Performance: New animation engine with react-native-reanimated

Enhanced Stability: Bug fixes and improved reliability

Future-Ready: Foundation for upcoming features and Tailwind v4 support

Improved Animation Capabilities: Smoother animations with worklets

No Import Changes: v3 and v4 use identical import patterns (though components must be re-copied)

Automated Upgrade (Recommended)

The easiest way to upgrade is using our automated CLI command:

npx gluestack-ui upgrade

This command will:

Auto-detect your current version (v2 or v3)

Upgrade to v4 automatically

Install all required dependencies

Update configuration files (babel.config.js for Expo/RN CLI)

Handle platform-specific packages (Next.js, Expo, React Native CLI)

Important Note

Important: After running the automated upgrade, you still need to:

Step 1:Update color tokens in
tailwind.config.js
and
gluestack-ui-provider/config.ts
(see Step 4 below)
Step 2:Re-copy all components using
npx gluestack-ui add <component>
(see Step 5 below)

For monorepos or custom setups, please follow the manual installation guide below.

Manual Migration to gluestack-ui v4

This guide provides detailed manual steps to migrate from gluestack-ui v3 to v4. Follow these steps carefully to ensure a smooth transition.

Migration Overview

The migration process involves several key steps:

Step 1:Backup and Preparation - Secure your codebase
Step 2:Package Management - Install new v4 packages
Step 3:Configuration Updates - Update Babel and Next.js configurations
Step 4:Color Token Migration - Update to shadcn-like color system
Step 5:Re-copy Components - Get updated component styles
Step 6:Clean Installation - Ensure dependency integrity
Step 7:Verification - Test your application

Understanding the Color Token Changes

v4 introduces a new color token system inspired by shadcn/ui. This provides better semantic naming and more consistent theming: New Color Tokens:

background

foreground

- Base application colors

card

card-foreground

- Card surfaces

popover

popover-foreground

- Popover/dropdown surfaces

primary

primary-foreground

- Primary brand color

secondary

secondary-foreground

- Secondary brand color

muted

muted-foreground

- Muted/subtle content

accent

accent-foreground

- Accent highlights

destructive

destructive-foreground

- Error/danger states

border

- Border colors

input

- Input field borders

ring

- Focus ring colors

These tokens use HSL color space with CSS variables for easy theming and dark mode support.

Step 1: Backup and Preparation

Check Git Status

Before proceeding, ensure your project has no uncommitted changes:

git status

If you have uncommitted changes, either commit them or stash them:

# Commit changes
git add .
git commit -m "Pre-migration to v4 backup"

# Or stash changes
git stash

Verify Current Version

Check your

package.json

to confirm you're on v3:

{
  "dependencies": {
    "@gluestack-ui/core": "^3.0.10",
    "@gluestack-ui/utils": "^3.0.11"
  }
}

Step 2: Install v4 Packages

Install New Packages

Install the new gluestack-ui v4 packages and required dependencies:

npm install @gluestack-ui/core@alpha @gluestack-ui/utils@alpha react-native-reanimated@~4.2.1 react-native-worklets@^0.7.1 @legendapp/motion@^2.4.0 tailwind-variants@^0.1.20 react-native-svg@^15.12.0 nativewind@^4.1.23 @gluestack/ui-next-adapter@alpha react-native-web@^0.20.0 react-native-safe-area-context@^5.6.1 react-aria@^3.41.1 react-stately@^3.39.0 dom-helpers@^5.2.1

Or with yarn:

yarn add @gluestack-ui/core@alpha @gluestack-ui/utils@alpha react-native-reanimated@~4.2.1 react-native-worklets@^0.7.1 @legendapp/motion@^2.4.0 tailwind-variants@^0.1.20 react-native-svg@^15.12.0 nativewind@^4.1.23 @gluestack/ui-next-adapter@alpha react-native-web@^0.20.0 react-native-safe-area-context@^5.6.1 react-aria@^3.41.1 react-stately@^3.39.0 dom-helpers@^5.2.1

Important Note

Note: Use

--legacy-peer-deps

flag if you encounter peer dependency resolution issues.

New Dependencies Explained

Package	Purpose	Required For
react-native-reanimated@~4.2.1	Primary animation engine for v4	All Projects
react-native-worklets@^0.7.1	Required by react-native-reanimated	All Projects
@legendapp/motion@^2.4.0	Used by some components (Tooltip, ActionSheet, Select)	All Projects
tailwind-variants@^0.1.20	Enhanced variant system	All Projects
nativewind@^4.1.23	Updated styling engine	All Projects

Step 3: Update Configuration Files

Step 3.1: Update Babel Config (Expo/React Native CLI Only)

For Expo and React Native CLI projects, you must add the

react-native-worklets/plugin

to your

babel.config.js

: Before:

module.exports = function (api) {
api.cache(true);
return {
  presets: ['babel-preset-expo'],
  plugins: [
    // your existing plugins
  ],
};
};

After:

module.exports = function (api) {
api.cache(true);
return {
  presets: ['babel-preset-expo'],
  plugins: [
    // your existing plugins
    'react-native-worklets/plugin', // Add this line
  ],
};
};

Important Note

Important: The

react-native-worklets/plugin

must be included for react-native-reanimated to work properly.

Step 3.2: Update Next.js Configuration (Next.js Only)

Ensure your

@gluestack/ui-next-adapter

is updated to v4. The configuration syntax remains the same:

import { withGluestackUI } from '@gluestack/ui-next-adapter';

const nextConfig = {
// ... your config
};

export default withGluestackUI(nextConfig);

Step 4: Update Color Tokens (Breaking Change)

Step 4.1: Update Tailwind Config

⚠️ Important: v4 introduces a new shadcn-like color token system. You need to update your

tailwind.config.js

with the new color definitions. Replace your existing color configuration with the new v4 color tokens:

/** @type {import('tailwindcss').Config} */
module.exports = {
// ... other config
theme: {
  extend: {
     colors: {
      // New v4 color tokens (shadcn-like)
      foreground: 'rgb(var(--foreground)/<alpha-value>)',
      card: {
        DEFAULT: 'rgb(var(--card) / <alpha-value>)',
        foreground: 'rgb(var(--card-foreground) / <alpha-value>)',
      },
      popover: {
        DEFAULT: 'rgb(var(--popover) / <alpha-value>)',
        foreground: 'rgb(var(--popover-foreground) / <alpha-value>)',
      },
      muted: {
        DEFAULT: 'rgb(var(--muted) / <alpha-value>)',
        foreground: 'rgb(var(--muted-foreground) / <alpha-value>)',
      },
      destructive: {
        DEFAULT: 'rgb(var(--destructive) / <alpha-value>)',
      },
      border: 'rgb(var(--border)/<alpha-value>)',
      input: 'rgb(var(--input)/<alpha-value>)',
      ring: 'rgb(var(--ring) / <alpha-value>)',
      white: 'rgb(255 255 255)',
   
      primary: {
        DEFAULT: 'rgb(var(--primary)/<alpha-value>)',
        foreground: 'rgb(var(--primary-foreground)/<alpha-value>)',
      },

      secondary: {
        DEFAULT: 'rgb(var(--secondary)/<alpha-value>)',
        foreground: 'rgb(var(--secondary-foreground)/<alpha-value>)',
      },

      typography: {
        white: '#FFFFFF',
        gray: '#D4D4D4',
        black: '#181718',
      },

      background: {
        DEFAULT: 'rgb(var(--background)/<alpha-value>)',
      },
      accent: {
        DEFAULT: 'rgb(var(--accent)/<alpha-value>)',
        foreground: 'rgb(var(--accent-foreground)/<alpha-value>)',
      },
    },
  },
},
};

Step 4.2: Update GluestackUIProvider Config

Update your

components/ui/gluestack-ui-provider/config.ts

(or wherever your provider config is located) with the new color token definitions:

'use client';
import { vars } from 'nativewind';

export const config = {
light: vars({
  '--primary': '23 23 23',
  '--primary-foreground': '250 250 250',
  '--card': '255 255 255',
  '--secondary': '245 245 245',
  '--secondary-foreground': '23 23 23',
  '--background': '255 255 255',
  '--popover': '255 255 255',
  '--popover-foreground': '10 10 10',
  '--muted': '245 245 245',
  '--muted-foreground': '115 115 115',
  '--destructive': '231 0 11',
  '--foreground': '10 10 10',
  '--border': '229 229 229',
  '--input': '229 229 229',
  '--ring': '212 212 212',
  '--accent': '247 247 247',
  '--accent-foreground': '52 52 52',
}),
dark: vars({
  '--primary-foreground': '23 23 23',
  '--primary': '255 245 245',
  '--card': '23 23 23',
  '--secondary': '38 38 38',
  '--secondary-foreground': '250 250 250',
  '--background': '10 10 10',
  '--popover': '23 23 23',
  '--popover-foreground': '250 250 250',
  '--muted': '38 38 38',
  '--muted-foreground': '161 161 161',
  '--destructive': '255 100 103',
  '--foreground': '250 250 250',
  '--border': '46 46 46',
  '--input': '46 46 46',
  '--accent': '38 38 38',
  '--accent-foreground': '250 250 250',
  '--ring': '115 115 115',
}),
};

Important Note

Note: These are the default color tokens. You can customize them to match your brand colors.

Step 5: Re-copy All Components

⚠️ Critical Step: Due to the color token changes and animation library updates, you must re-copy all components from the CLI.

Re-copy Components One by One

For each component you're using, run:

# Example: Re-copy Button component
npx gluestack-ui add button

# Re-copy all components you're using
npx gluestack-ui add accordion
npx gluestack-ui add alert
npx gluestack-ui add avatar
# ... etc

When prompted to overwrite existing components, select Yes to replace them with the v4 versions.

Important Note

Important: The CLI will automatically:

Update component styles to use new color tokens

Replace

@legendapp/motion

with

react-native-reanimated

where applicable

Ensure components use the correct animation imports

Backup Custom Changes

If you've customized any component styles:

Step 1:
Before re-copying: Backup your customizations
```
cp -r components/ui components/ui-backup
```
Step 2: After re-copying: Manually re-apply your customizations to the new component files

Step 7: Clean Installation

To ensure all dependencies are properly resolved, perform a clean installation:

# Remove node_modules and package-lock.json
rm -rf node_modules package-lock.json

# Reinstall dependencies
npm install

Step 8: No Import Changes Required! 🎉

Great news! v3 and v4 use identical import patterns, so you don't need to update any import statements:

// These imports work in both v3 and v4!
import { createButton } from '@gluestack-ui/core/button/creator';
import { createRadio } from '@gluestack-ui/core/radio/creator';
import { flush } from '@gluestack-ui/utils/nativewind-utils';
import { tva } from '@gluestack-ui/utils/nativewind-utils';

Important Note

However: While imports don't change, you still need to re-copy components (Step 5) due to internal style and animation changes.

Step 9: Verification and Testing

Verify Migration Success

After completing the migration:

1. Check for compilation errors:

npm run build

2. Run your development server:

npm run dev

3. Test animated components:

Test components that use the new animation system:

Accordion

Drawer

Modal

Popover

Toast

4. Test your application functionality:

Ensure all your components render and behave correctly.

Common Issues and Solutions

Babel Plugin Not Working

Issue: Animated components not working in Expo/React Native. Solution: Ensure

react-native-worklets/plugin

is added to

babel.config.js

and restart your development server:

# Clear cache and restart
npx expo start --clear

# For React Native CLI
npx react-native start --reset-cache

Metro Bundler Issues

Issue: Metro bundler errors after upgrade. Solution: Clear Metro cache and restart:

# Expo
npx expo start --clear

# React Native CLI
npx react-native start --reset-cache

Build Errors

Issue: Build fails with dependency resolution errors. Solution:

Step 1:
Use
--legacy-peer-deps
flag:
```
npm install --legacy-peer-deps
```

Step 2: Or try clearing cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Animation Performance Issues

Issue: Animations are laggy or not smooth. Solution: Ensure Hermes is enabled (it's required for react-native-reanimated): For React Native CLI, check

android/app/build.gradle

project.ext.react = [
    enableHermes: true,
]

For Expo, Hermes is enabled by default in SDK 50+.

Migration Checklist

Use this checklist to track your migration progress:

Preparation

[ ] Committed or stashed all changes

[ ] Verified current version is v3

[ ] Created project backup

Package Management

[ ] Installed v4 packages

[ ] Installed react-native-reanimated and worklets

[ ] Updated Next.js adapter (if applicable)

Configuration Updates

[ ] Updated babel.config.js (Expo/RN CLI)

[ ] Verified Next.js configuration (Next.js)

[ ] Updated tailwind.config.js with new color tokens

[ ] Updated gluestack-ui-provider/config.ts with new color tokens

Component Updates

[ ] Backed up custom component changes

[ ] Re-copied all components using CLI

[ ] Re-applied custom modifications (if any)

[ ] Verified component styles look correct

Clean Installation

[ ] Performed clean installation

[ ] Cleared Metro/build cache

Testing

[ ] Project builds successfully

[ ] Development server runs

[ ] Animated components work correctly

[ ] Color theming works in light mode

[ ] Color theming works in dark mode

[ ] All functionality tested

Finalization

[ ] Committed changes

[ ] Updated documentation

[ ] Deployed to staging for testing

Platform-Specific Notes

Next.js Projects

Ensure

@gluestack/ui-next-adapter@alpha

is installed

No babel configuration changes needed

SSR/RSC continues to work as before

Expo Projects

Works with Expo SDK 50+

Hermes is enabled by default

Make sure to add worklets plugin to babel.config.js

Clear cache with

npx expo start --clear

React Native CLI Projects

Enable Hermes in build configuration

Add worklets plugin to babel.config.js

Clear cache with

npx react-native start --reset-cache

Animation System Changes

Components Using react-native-reanimated (New in v4)

These components now use

react-native-reanimated

for better performance:

Accordion

Drawer

Modal

Popover

Toast

Components Still Using @legendapp/motion

These components continue to use

@legendapp/motion

Tooltip

ActionSheet

Select

Important Note

Note: Both animation libraries are automatically installed and configured by the CLI.

Next Steps

After successful migration:

Step 1:Test thoroughly: Test all components in your application
Step 2:Monitor performance: Check if animations perform better with the new engine
Step 3:Update documentation: Revise any project-specific documentation
Step 4:Stay updated: Follow gluestack-ui releases for future updates

Support

If you encounter issues during migration:

Check the

gluestack-ui documentation

Review common issues in this guide

Join our

Discord community

for help

Report bugs on

GitHub

Remember to test thoroughly in a development environment before deploying to production!

Edit this page on GitHub