gluestack-ui Documentation

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 : Copy Section

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

<>

</>

Property Combinations : Copy Section

<>

</>

Update config : Copy Chapter

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

Config conversion : Copy Section

// 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 : Copy Section

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

For Tailwind config configuration please refer to this .

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

Limitations (Descendant Styling) : Copy Section

• 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

//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 : Copy Chapter

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

Before:

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

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

After:

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

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

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

Before:

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

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

After:

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

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

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

Before:

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

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

After:

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

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

Applying basic layout stylings :

Before:

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

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

After:

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

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

Applying basic layout stylings in different color modes :

Before:

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

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

After:

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:

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

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

After:

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:

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

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

After:

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:

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

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

After:

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

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

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

Before:

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:

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 Copy Chapter

title: Changelog | gluestack-ui Copy Chapter

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

Troubleshooting

If you encounter any issues while using nativewind, please refer to the nativewind troubleshooting guide.

Common Issues Copy Chapter

1. "dark:" Variant Not Working as Expected Copy Section

If you are using dark: and experiencing unexpected behavior, ensure that you have followed the documentation for dark mode configuration correctly.

2. Toast Inside Modal Not Functioning Copy Section

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

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 Copy Section

If encountering flashing issues in Next.js:

• Refer to the installation documentation, click on manual, and ensure that step 4 is correctly configured.

4. TailwindCSS Classnames Not Overriding in react-native-web Copy Section

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

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

Known Issues Copy Chapter

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

Still Facing Issues? Copy Chapter

If you continue to experience issues, please create an issue on GitHub.

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

title: Roadmap | gluestack-ui Copy Chapter

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

Roadmap

Upcoming Copy Section

• 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 Copy Section

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

Live Copy Section

• 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 Copy Chapter

title: Releases | gluestack-ui Copy Chapter

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

Releases

To view releases, please visit GitHub releases.

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

title: FAQs | gluestack-ui Copy Chapter

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

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

FAQs

Migration and Compatibility Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

• 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.

Technical Questions Copy Chapter

• Are there any known issues with gluestack v2?

  • You can check out the troubleshooting 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 Copy Chapter

• 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.