## File: README.md

gluestack v5 is here!
Our biggest release yet is live today — with support for NativeWind v5 (Tailwind v4), optimized CLI performance, Expo Router first, and state-of-the-art native components.
# gluestack-ui: React Native & Expo Components & Patterns

gluestack-ui is a library of copy-pasteable components & patterns crafted with Tailwind CSS (NativeWind).

[](https://github.com/gluestack/gluestack-ui)

[](https://www.npmjs.com/package/@gluestack-ui/utils) [](https://github.com/gluestack/gluestack-ui/commits)

[](https://github.com/gluestack/gluestack-ui/actions/workflows/expo-latest.yml)

<h3 align="center">
  <a href="https://github.com/gluestack/gluestack-ui">
    
  </a>
  
  
 </h3>

## Introduction

**gluestack-ui v5** offers customizable, beautifully designed components for your native projects. Unlike traditional libraries, it's not a pre-packaged dependency. Choose the components you need and copy-paste them directly into your Expo and React Native projects.

## Documentation

You can find detailed documentation for each component, including a list of props and examples, in https://gluestack.io/ui/docs website.

## Features

- **NativeWind v5 / Tailwind v4 Integration:** Tailwind CSS support for seamless styling across native platforms.
- **Modular Architecture:** Pick and choose the components you need without unnecessary bloat.
- **Expo Router First:** Out-of-the-box integration with the latest Expo Router.
- **Flexible Theming:** Customize your components with ease using theming tokens and configuration.
- **Accessibility:** Built with robust accessibility features to ensure inclusivity.
- **Frequent updates:** We are constantly working on improving the library and adding new components. Follow us on GitHub to stay up-to-date on the latest releases and features.
- **Community support:** Need help using the library or have a suggestion for a new feature? Join our [Discord](https://discord.com/invite/95qQ84nf6f) channel to connect with the community and get support.

## Installing **gluestack-ui v5**

To get started with **gluestack-ui v5**, you must have an existing Expo or React Native project. Then, simply run the following command:

```bash
npx gluestack-ui init
```

For detailed installation instructions, visit the [gluestack-ui v5 installation guide](https://gluestack.io/ui/docs/home/getting-started/installation).

## Tech Stack

TypeScript, React Native, Expo, Tailwind CSS, NativeWind

## Getting Started

- **Install gluestack-ui:** Follow the [installation guide](https://gluestack.io/ui/docs/home/getting-started/installation).
- **Add Components:** Use our CLI to add components to your project, or simply copy-paste from our documentation.
- **Customize:** Tailor the components to fit your project's needs using theming tokens and configuration.
- **Build:** Start building your app with a consistent, accessible, and high-performance UI.

## Migration from gluestack-ui v3 / v4

If you're migrating from earlier versions, check our [migration guide](https://gluestack.io/ui/docs) to upgrade to v5.

## Created By GeekyAnts

GeekyAnts is a team of React Native experts who love open-source and solving developer problems. We’ve been working on React Native since 2015 and have designed and built React Native apps for almost 200+ clients across the globe. Our clients include startups to big enterprises! Need help with your React Native app?

[Contact Us](https://geekyants.com/?utm_source=gluestack_github&utm_medium=read_me&utm_campaign=gluestack_integration)

## Contributing

We welcome contributions to the `gluestack-ui`. If you have an idea for a new component or a bug fix, please read our [contributing guide](./CONTRIBUTING.md) instructions on how to submit a pull request.

## License

Licensed under the MIT License, Copyright © 2026 GeekyAnts. See [LICENSE](https://github.com/gluestack/gluestack-ui/blob/main/LICENSE) for more information.

---

## File: example/storybook-v7/README.md

# getting started

```sh
npx create-expo-app --template expo-template-storybook AwesomeStorybook
```

or

```sh
yarn create expo-app --template expo-template-storybook AwesomeStorybook
```

# app

```sh
yarn start
```

# Ondevice

In this template you can now run `yarn storybook` to start ondevice storybook or `yarn start` to start your expo app.
This works via env variables and expo constants.

```sh
# either
yarn storybook

# ios
yarn storybook:ios

# android
yarn storybook:android
```

If you add new stories on the native (ondevice version) you either need to have the watcher running or run the stories loader

To update the stories one time

```sh
yarn storybook-generate
```

# Web

Start react native web storybook:

```
yarn storybook:web
```

build react native web storybook:

```sh
yarn build-storybook
```

---

## File: example/storybook-nativewind/src/guides/recipes/linear-gradient/index.nw.stories.mdx

---
title: gluestack-ui LinearGradient | Installation, Usage, and API
pageTitle: LinearGradient

pageDescription: A LinearGradient component is a reusable graphical element that helps create linear gradients as background or styling effects within UI elements. A linear gradient is a gradual transition between two or more colors, creating a smooth progression of color changes along a straight line.

showHeader: true
---

import { Meta } from '@storybook/addon-docs';

<Meta title="with-nativewind/Guides/Recipes/LinearGradient" />

import { Tabs, CollapsibleCode } from '@gluestack/design-system';
import GradientImage from '../../../extra-components/nativewind/GradientImage';

This is an illustration of **Linear Gradient** component in `App.tsx` file.

<GradientImage/>

```jsx
import "./global.css";
import React, { useState } from "react";
import { Input, InputField, InputIcon, InputSlot } from "@/components/ui/input";
import { SafeAreaView } from "@/components/ui/safe-area-view";
import { GluestackUIProvider } from "@/components/ui/gluestack-ui-provider";
import { LinearGradient } from "@/components/ui/linear-gradient";
import { Heading } from "@/components/ui/heading";
import { Text } from "@/components/ui/text";
import { Center } from "@/components/ui/center";
import { Mail } from "lucide-react-native";

export default function App() {
  const [colorMode, setColorMode] = useState<"dark" | "light">("light");
  return (
    <SafeAreaView className="flex-1 justify-center items-center">
      <GluestackUIProvider mode={colorMode}>
        
          <Heading size="xl">Stay up to date</Heading>
          <Text className="text-center leading-[22px] my-2">
            Subscribe to our newsletter for the latest news and product updates.
          </Text>

          
            
            
              
            
          

          <LinearGradient
            className="w-full rounded-full items-center py-2"
            colors={["#8637CF", "#0F55A1"]}
            start={[0, 1]}
            end={[1, 0]}
          >
            <Text className="text-white font-semibold">Subscribe</Text>
          </LinearGradient>
        
      </GluestackUIProvider>
    </SafeAreaView>
  );
}
```



## Installation

<Tabs value="expo" type="section">
  <Tabs.TabList>
      <Tabs.Tab value="expo">
        <Tabs.TabTitle>Expo Linear Gradient</Tabs.TabTitle>
      </Tabs.Tab>
     <Tabs.Tab value="rn">
        <Tabs.TabTitle>React Native Linear Gradient</Tabs.TabTitle>
     </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="expo">
<>

### Step 1: Install the following dependencies:
```bash
npx expo install expo-linear-gradient
```

### Step 2: Copy and paste the following code into your project.
<CollapsibleCode>

```jsx 
%%-- File: guides/recipes/linear-gradient/expo-linear-gradient.tsx --%% 
```
</CollapsibleCode>

### Step 3: Update the import paths to match your project setup.
</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="rn"> 
<>

### Step 1: Install the following dependencies:
```bash
npm i react-native-linear-gradient
```

### Step 2: Copy and paste the following code into your project.
<CollapsibleCode>

```jsx 
%%-- File: guides/recipes/linear-gradient/rn-linear-gradient.tsx --%% 
```
</CollapsibleCode>

### Step 3: Update the import paths to match your project setup.
</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

## API Reference

To use this component in your project, include the following import statement in your file.

```jsx
import { LinearGradient } from '@/components/ui/linear-gradient';
```

```jsx
export default () => <LinearGradient />;
```

---

## File: example/storybook-nativewind/src/guides/more/Upgrade to v2/index.nw.stories.mdx

---
title: Upgrade to v2 with codemod | gluestack-ui
---

import { Meta } from '@storybook/addon-docs';

<Meta title="with-nativewind/Guides/More/Upgrade to v2" />

import {
  Tabs,
  CollapsibleCode,
  CodePreview,
  Table,
  TableContainer,
  InlineCode,
} from '@gluestack/design-system';

# Upgrade to gluestack-ui v2 with Codemod

This guide provides detailed steps to upgrade from gluestack-ui v1 to gluestack-ui v2. With codemod you can automate the process of code transformations, making it easier and faster to migrate your project to gluestack-ui v2. By following this guide, you'll ensure a smooth transition with minimal manual adjustments.

## gluestack-ui v1 Usage Scenarios:

gluestack-ui v1 users can be divided into three scenarios:

- **Scenario 1** : Users who imported the gluestack-ui configuration from `@gluestack-ui/config`.
- **Scenario 2** : Users who exported the gluestack-ui configuration and made modifications to it (`gluestack-ui.config.ts`).
- **Scenario 3** : Users who exported components as well.



At this time, we fully support migration for users in **Scenario 1 and Scenario 2** using codemod.

### Overview of Steps to Follow (for  Scenario 1 and Scenario 2  Users)


1. **Initialize gluestack-ui v2**: `npx gluestack-ui@latest init`
2. **Setup Tailwind CSS**: `import "@/global.css"`
3. **Add All Components**: `npx gluestack-ui@latest add --all`
4. **Code Migration**: `npx @gluestack-ui/v2-codemod@latest `


## Step 1 : Initialize gluestack-ui v2

**Run the below command to setup the project**:

```
npx gluestack-ui@latest init
```

To refer more about the gluestack-ui v2 installation, check [this](https://gluestack.io/ui/docs/home/getting-started/installation).


> Installation using gluestack-ui CLI in Expo projects supports for Expo SDK 50 and above only. For Expo SDK < 49, please refer to the manual installation guide [here](https://gluestack.io/ui/docs/home/getting-started/installation).

## Step 2 : Setup Tailwind CSS

Import `global.css` / `globals.css` where Tailwind directives are defined.

```jsx
import { GluestackUIProvider } from '@/components/ui/gluestack-ui-provider';
import '@/global.css';

export default function App() {
  return <GluestackUIProvider>{/* Your code */}</GluestackUIProvider>;
}
```
## Step 3 : Add All Components

To add all the components run the following command:

```jsx
npx gluestack-ui@latest add --all
```

You can add only the necessary components instead of including all. Check [here](https://gluestack.io/ui/docs/components/heading).

<CollapsibleCode>
  
```jsx 
npx gluestack-ui@latest add heading 
```
</CollapsibleCode>

## Step 4 : Code Migration

### Codemod
The gluestack-ui v2 migration process has been streamlined with the creation of a codemod. This codemod automates the conversion of your existing v1 code to v2, ensuring a smooth transition. Here’s what the codemod does:

##### Style Migration:
  - It migrates all your existing stylings in v1 code to the appropriate v2 code.
  - The migrated styles will match the styling conventions used in NativeWind.
##### Config Migration:
  - If you have a custom v1 configuration, the codemod will also migrate this configuration to be compatible with v2.
##### Limitations:
  - Descendant Styling ( As it’s not supported in NativeWind at the moment)
  - Value of `sx` prop is variable
#### Please proceed with the following steps to continue the migration:
<Tabs value="cli" type="section">
  <Tabs.TabList>
      <Tabs.Tab value="cli">
        <Tabs.TabTitle>With Codemod</Tabs.TabTitle>
      </Tabs.Tab>
     <Tabs.Tab value="manual">
        <Tabs.TabTitle>Manual</Tabs.TabTitle>
     </Tabs.Tab>
  </Tabs.TabList>
  <Tabs.TabPanels>
    <Tabs.TabPanel value="cli">
<>
### Run the following command :

```bash
npx @gluestack-ui/v2-codemod@latest 
```

</>
    </Tabs.TabPanel>
    <Tabs.TabPanel value="manual"> 
<>

To manually change the styling of any respective v1 specific style to v2 style we can follow this property mapper to ideally convert the styles to `NativeWind` stylings.

### Property Mapper :

In this property mapper table you can find all the properties of v1 and how they can be written in v2

<>
  
  
</>

### Property Combinations :

<>
  
  
</>

## Update config :

For config conversion,we need to make changes in two files gluestack-ui config file & Tailwind CSS config file.

### Config conversion :

```jsx
// gluestack-ui v1

// Without CSS Variables
{
  tokens: {
    ...defaultConfig.tokens,
    colors: {
      ...defaultConfig.tokens.colors,
      primary0: "#F5F3FF",
      primary50: "#999999",
    },
  },
};

// gluestack-ui v2

// With CSS variables
{
  light: vars({
    "--color-primary-0": "#F5F3FF",
    "--color-primary-50": "#999999",
  }),
};

// Updating the config(nativewind) file
{
  extends: {
    colors: {
      primary: var(--colors-primary),
    },
  },
};

// Different color modes
{
  light: vars({
    "--color-background-0": "#B3B3B3",
    "--color-background-50": "#999999",
  }),
  dark: vars({
    "--color-background-0": "#111827",
    "--color-background-50": "#171717",
  }),
};

```

### Tailwind Config conversion :

```
/* Detailed source-code truncated for AI context efficiency. */
```

For Tailwind config configuration please refer to [this](https://tailwindcss.com/docs/configuration) .

</>
    </Tabs.TabPanel>
  </Tabs.TabPanels>
</Tabs>

### Limitations (Descendant Styling) :

- Descendant styling will not be resolved and we’ll keep it as it is.
- You can update it manually by moving it to the respective element where the style is required

```jsx
//Before:

import { Box, Text } from '@gluestack-ui/themed';
export default function App() {
  return (
    
      <Text>Simple Text</Text>
    
  );
}

//After:

import { Box } from '@/components/ui/box';
import { Text } from '@/components/ui/text';

//descendant style will remain as it is.
export default function App() {
  return (
    
      <Text>Simple Text</Text>
    
  )
}
//Manual Changes:
//Update the descendant styling:
import { Box } from '@/components/ui/box';
import { Text } from '@/components/ui/text';

//descendant style will remain as it is.
//color:'white' --> text-white
export default function App() {
  return (
    
      <Text className="text-white">Simple Text</Text>
    
  )
}
```

## Examples of some property combinations :


**Applying styles in different color modes (light/dark)** :

**Before**:

```jsx
import { Box } from '@gluestack-ui/themed';

export default function App() {
  return (
    
      Simple Text
    
  );
}
```

**After**:

```jsx
import { Box } from '@/components/ui/box';

export default function App() {
  return Simple Text;
}
```

**Applying styles for different media queries (sm/md/lg) using `@`**:

**Before**:

```jsx
import { Box } from '@gluestack-ui/themed';

export default function App() {
  return (
    
      Simple Box
    
  );
}
```

**After**:

```jsx
import { Box } from '@/components/ui/box';

export default function App() {
  return (
    Simple Box
  );
}
```

**Applying styles for different media queries (sm/md/lg) using `$`** :

**Before**:

```jsx
import { Box } from '@gluestack-ui/themed';

export default function App() {
  return (
    
      Simple Box
    
  );
}
```

**After**:

```jsx
import { Box } from '@/components/ui/box';

export default function App() {
  return (
    Simple Box
  );
}
```

**Applying basic layout stylings** :

**Before**:

```jsx
import { Box } from '@gluestack-ui/themed';

export default function App() {
  return (
    
      Simple Box
    
  );
}
```

**After**:

```jsx
import { Box } from '@/components/ui/box';

export default function App() {
  return Simple Box;
}
```

**Applying basic layout stylings in different color modes** :

**Before**:

```jsx
import { Box } from '@gluestack-ui/themed';

export default function App() {
  return (
    
      Simple Box
    
  );
}
```

**After**:

```jsx
import { Box } from '@/components/ui/box';

//By default if you don't mention any mode it's take light mode.
export default function App() {
  return Simple Box;
}
```

**Applying styles for different action states (hover/active etc..,)** :

**Before**:

```jsx
import { Box } from '@gluestack-ui/themed';

export default function App() {
  return (
    
      Simple
    
  );
}
```

**After**:

```jsx
import { Box } from '@/components/ui/box';

//If not mentioned any mode explicitly then it's gonna take light mode only.
export default function App() {
  return (
    
      Simple
    
  );
}
```

**Applying styles for different platforms (mobile/web/android/ios)** :

**Before**:

```jsx
import { Text } from '@gluestack-ui/themed';

export default function App() {
  return (
    <Text
      sx={{
        _ios: {
          marginTop: '$1',
        },
        _android: {
          marginTop: '$2',
        },
      }}
    >
      gluestack-ui
    </Text>
  );
}
```

**After**:

```jsx
import { Text } from '@/components/text';

export default function App() {
  return <Text className="ios:mt-1 android:mt-2">gluestack-ui</Text>;
}
```

**Applying styles for different color modes at different media queries** :

**Before**:

```jsx
import { Center } from '@gluestack-ui/themed';

export default function App() {
  return (
    
  );
}
```

**After**:

```jsx
import { Center } from '@/components/center';

export default function App() {
  return (
    
  );
}
```

**Descendant Styling (this type of styling is not supported by NativeWind)** :

**Before**:

```jsx
import { CheckboxLabel, Text } from '@gluestack-ui/themed';

export default function App() {
  return (
    <CheckboxLabel
      sx={{
        bg: '$blue500',
        _text: {
          fontSize: '$sm',
          color: '$primary500',
        },
      }}
    >
      <Text>gluestack-ui</Text>
    </CheckboxLabel>
  );
}
```

**After**:

```jsx
import { CheckboxLabel } from '@/components/checkbox';
import { Text } from '@/components/text';

// we need to remove the descendant styling from parent element and add that
// styling to all the child elements
export default function App() {
  return (
    <CheckboxLabel className="bg-blue-500">
      <Text className="text-sm text-primary-500">gluestack-ui</Text>
    </CheckboxLabel>
  );
}
```

---

## File: example/storybook-nativewind/src/guides/more/Troubleshooting/index.stories.mdx

---
title: Changelog | gluestack-ui
---

import { Canvas, Meta, Story } from '@storybook/addon-docs';

<Meta title="common/Guides/More/Troubleshooting" />

# Troubleshooting

If you encounter any issues while using nativewind, please refer to the nativewind [troubleshooting guide](https://www.nativewind.dev/v4/guides/troubleshooting).

## Common Issues

### 1. "dark:" Variant Not Working as Expected

If you are using `dark:` and experiencing unexpected behavior, ensure that you have followed the documentation for [dark mode configuration](/home/theme-configuration/dark-mode) correctly.

### 2. Toast Inside Modal Not Functioning

When using `Toast` inside a `Modal`, ensure that you have added the `OverlayProvider` from `@gluestack-ui/overlay` to the root of your application.

```jsx
import { OverlayProvider } from '@gluestack-ui/overlay';
import { GluestackUIProvider } from '@/components/ui/gluestack-ui-provider';

const App = () => {
  return (
    <GluestackUIProvider>
      <OverlayProvider>
        <YourApp />
      </OverlayProvider>
    </GluestackUIProvider>
  );
};
```

### 3. Flashing Issue in Next.js

If encountering flashing issues in Next.js:

- Refer to the [installation documentation](https://gluestack.io/ui/nativewind/docs/home/getting-started/installation), click on manual, and ensure that step 4 is correctly configured.

### 4. TailwindCSS Classnames Not Overriding in react-native-web

To ensure Tailwind styles override with higher specificity, add `important: 'html'` to your `tailwind.config.js`.

```jsx
// tailwind.config.js
module.exports = {
  ...
  important: 'html',
  ...
}
```

## Known Issues

- `placeholder` does not work with CSS tokens.
- `dark:` does not function with "class" as a strategy in native devices.

## Still Facing Issues?

If you continue to experience issues, please create an issue on [GitHub](https://github.com/gluestack/gluestack-ui).

---

## File: example/storybook-nativewind/src/guides/more/Roadmap/index.nw.stories.mdx

---
title: Roadmap | gluestack-ui
---

import { Canvas, Meta, Story } from '@storybook/addon-docs';

<Meta title="with-nativewind/Guides/More/Roadmap" />

# Roadmap

### Upcoming

- **New Components release**
  - Circular Progress
  - Segmented controls
  - Tabs
- **Features / Enhancements**
  - Nested Menu
  - Tooltip Arrow
  - Example Improvement
- **Utility Props** support for nativewind
- **Hooks**
  - useMedia
  - useColorMode

### In Progress

- **gluestack-ui v2 release**
- **Component Redesign**
  - Alert
  - Popover
  - Toast
  - AlertDialog
  - Actionsheet
  - Menu
- **Performance Benchmarking**
- **Features**
  - Hovered Menu

### Live

- **New Components**
  - Grid
  - BottomSheet
  - Skeleton
- **Vscode Snippet support** for gluestack-v2
- **Hooks**
  - useBreakPointValue
- **Universal Starter Kit**
- **gluestack-ui CLI**
- **CodeMode v1 → v2**

---

## File: example/storybook-nativewind/src/guides/more/Releases/index.nw.stories.mdx

---
title: Releases | gluestack-ui
---

import { Canvas, Meta, Story } from '@storybook/addon-docs';

<Meta title="with-nativewind/Guides/More/Releases" />

# Releases

To view releases, please visit [GitHub releases](https://github.com/gluestack/gluestack-ui/releases).

---

## File: example/storybook-nativewind/src/guides/more/FAQs/index.nw.stories.mdx

---
title: FAQs | gluestack-ui
---

import { Canvas, Meta, Story } from '@storybook/addon-docs';

import {
  Table,
  TableContainer,
} from '@gluestack/design-system';


<Meta title="with-nativewind/Guides/More/FAQs" />

# FAQs

## Migration and Compatibility

- **How do I migrate from gluestack v1 to v2?**

  - We have a detailed migration guide with codemod.

- **Will gluestack v2 be compatible with my current project?**

  - Yes, you need to follow a few steps to get your project up and running.

- **What are the major differences between gluestack v1 and v2?**

<>
 
  
</>

## New Features and Improvements

- **What are the new features in gluestack v2?**

  - Tailwind CSS className support.
  - Partial RSC support.
  - NativeWind as a styling library.
  - Copy-Pastable components.

- **How does gluestack v2 improve performance compared to v1?**

  - Coming soon...

- **Are there any new components or APIs in gluestack v2?**
  - Yes, we have Skeleton, Table, Bottomsheet, Grid, and many more to come.

## Support and Community

- **What kind of support is available for gluestack v1?**

  - We will provide maintenance and support for gluestack-ui v1 for a limited time to ensure a smooth transition.

- **How can I provide feedback or report bugs?**
  - You can create a GitHub issue on our [repo](https://github.com/gluestack/gluestack-ui).

## Technical Questions

- **Are there any known issues with gluestack v2?**

  - You can check out the [troubleshooting](https://gluestack.io/ui/docs/guides/more/troubleshooting#known-issues) page for this.

- **Are there any deprecated features from v1 that are not available in gluestack v2?**
  - Descendant Styling.
  - Utility Props.
  - Property Resolver.
  - Passing Prop.

## Adoption and Integration

- **How do I integrate gluestack v2 with other libraries and frameworks?**

  - It works out of the box. You can check out our integration of Gorhom Bottom Sheet for more reference.

- **What are the best practices for using gluestack v2 in production?**
  - **Purge Unused CSS**: Enable PurgeCSS to remove unused styles in production.
  - **Use CDN for Tailwind**: Serve Tailwind CSS via a CDN for faster load times.
  - **Optimize Build Process**: Use tools like PostCSS and Autoprefixer for better performance.
  - **Minimize Custom CSS**: Stick to Tailwind's utility classes to keep your CSS file small.
  - **Don't Include Unused Utilities**: Avoid adding unused utilities in your configuration to keep the CSS file lightweight.
  - **Don't Ignore Responsive Design**: Ensure your design is responsive to avoid performance issues on different devices.
  - **Don't Overload with Plugins**: Use only necessary plugins to avoid bloating the CSS file.
  - **Don't Skip Testing**: Regularly test your site's performance and make adjustments as needed.