Looking for documentation on gluestack-ui with NativeWind (alpha) version? Refer to this link.

Introduction

gluestack-ui is intentionally designed as an unstyled library, providing you with the flexibility to style your components as you prefer.
gluestack-ui provides a collection of unstyled components that can be styled according to a specific theme or design language. These components are reusable, consistent, interactive, and are accessible on the web, iOS, and Android.

Key Features

  • Unstyled by Default: All gluestack-ui components are unstyled by default, allowing users to define their own styles or use a styling library.
  • Optional Styling: Users have the choice to apply custom styles to components, tailoring the appearance to match their project's requirements and design language.
  • Accessibility: Components are designed to be functional, and accessible, and follow the WAI-ARIA Authoring Practices guidelines, ensuring a seamless user experience.
  • Lightweight: gluestack-ui is lightweight, promoting better performance and faster load times.

Styling Options

The gluestack-ui provides multiple flexible styling options to customize the appearance of components according to your preferences.

Default Components

By default, when you use @gluestack-ui/themed, you get plain, unstyled components.
But, it also comes with a package called @gluestack-ui/config, which has ready-made styles for all the components. So, you can choose these styles if you like. Please visit Themed Library for more information.
And, the cool part is, you can even create your own unique style if you want to give these components a personal touch.
Note: If you want to create your own design system with these components, it's advisable to refer to the customization guide available guide.
import { GluestackUIProvider, Button, ButtonText } from "@gluestack-ui/themed"
function App() {
return (
<GluestackUIProvider>
<Button backgroundColor="purple" padding={12}>
<ButtonText color="white">Hello world</ButtonText>
</Button>
</GluestackUIProvider>
)
}
When we use the GluestackUIProvider, it doesn't come with any pre-defined styles. So, by default, all the components you get from @gluestack-ui/themed are unstyled.
However, you can make these components look the way you want by adding your own unique styles.

Custom Components

Note: Using custom components is recommended in case you are building your own design system and want to create everything from scratch.
Let's try creating an unstyled Button component
We utilize a function named createButton for the creation of a customized button component. This function accepts a configuration object that contains the styled components you wish to apply to the button. For guidance on the usage of styled components, you can refer gluestack.io/style. These styled components can be generated using the styled function, which is exported by @gluestack-style/react. Here is a basic example provided below.
// import {styled} from '@gluestack-style/react';
// import {View, Pressable, Text as RNText, ActivityIndicator} from 'react-native';
function App() {
const Root = styled(Pressable, {})
const Text = styled(RNText, {})
const Group = styled(View, {})
const Spinner = styled(ActivityIndicator, {})
const Icon = styled(View, {})
// Understanding the API
const Button = createButton({
Root,
Text,
Group,
Spinner,
Icon,
})
return (
<Button.Group>
<Button>
<Button.Text $dark-color="white">Hello world</Button.Text>
</Button>
</Button.Group>
)
}
In the above example, we are creating an accessible, universal Button component by using createButton function exported by @gluestack-ui/button package. We create various unstyled library using the API employed by styled function. These components are then passed as arguments to createButton function. Likewise, for each component, there exists a distinct package and API, specified in the documentation of the respective components.
Styling these components is achieved with the aid of the @gluestack-style/react library. We generate styled components and encapsulate them within an object, which is then provided as input to the function.

Usecase for unstyled components without any config

Let's say you want to use the Button component from @gluestack-ui/button package, but you don't want to use any of the pre-defined styles. In this case, you can use the createButton function without any configuration object. And you can pass inline styles without tokenization to style them.
// import {GluestackUIProvider, ButtonGroup, Button, ButtonText } from '@gluestack-style/react';
// import {View, Pressable, Text as RNText, ActivityIndicator} from 'react-native';
function App() {
return (
<GluestackUIProvider>
<ButtonGroup>
<Button backgroundColor="blue">
<ButtonText color="white">Hello world</ButtonText>
</Button>
</ButtonGroup>
</GluestackUIProvider>
)
}