Building Design Systems

Empower your development by creating a personalized design system with gluestack-ui. This enables you to build your own collection of components that match your vision.

Step 1: Create Your Own Package

If you are planning to build your own design system, you can directly fork gluestack-ui – a meticulously organized monorepo and begin shaping your design system upon this solid foundation.
  • This includes a component library package @gluestack-ui/themed in packages/themed directory.
  • This includes a theme package @gluestack-ui/config in packages/config directory.
  • This includes a storybook for both React and React Native in example/storybook directory.
Follow these steps after forking this repository:

Change library name

  • Navigate to the packages/themed and open package.json. (You can rename the folder if you need).
  • Locate the name field in the package.json file and update it to @myapp/components.
    "name": "@myapp/components"
    // ...
    Now your library @myapp/components has all primitive components from @gluestack-ui/themed by default.
  • Similarly, Navigate to the packages/config and open package.json. (You can rename the folder if you need).
  • Locate the name field in package.json file and update it to @myapp/config.
    "name": "@myapp/config"
    // ...
    Now your library @myapp/config has all primitive components from @gluestack-ui/config by default.

Update storybook configuration

Navigate to the example/storybook and make updates to the specified files below.
  • tsconfig.json: You'll need to update paths in tsconfig.json for TypeScript import resolution.
    // ... other configuration
    "compilerOptions": {
    // ...
    "paths": {
    "@myapp/components": ["../../packages/themed/src"],
    "@myapp/config": ["../../packages/config/src/gluestack-ui.config"],
    // ...
  • babel.config.js: You'll need to update alias in babel.config.ts file incase you've renamed the folder packages/themed or packages/config.
    // ... other configuration
    plugins: [
    alias: {
    '@gluestack-ui/themed': path.join(
    // ... other configuration

Step 2: Customize Tokens and Components

Theme Tokens

Theme tokens and other configuration is present in packages/config/src. You have the flexibility to modify these tokens as per your requirements.
Check this for more details.


You can customize the styling of all primitive components. You can modify styling in packages/config/src/theme/<ComponentName>.ts/ for a particular component. You can add and modify property value and variants based on your need.
Create a custom component To create your own custom component. You need to follow these steps:
  1. Step
    Create a folder inside packages/themed/src/components/Circle
  2. Step
    Create a folder styled-components/ inside packages/themed/src/components/Circle to keep components.
  3. Step
    Create a styled component using @gluestack-style/react in Root.tsx, this will be an unstyled component initially with just component name.
export const Root = styled(View, {}, { componentName: "Circle" })
  1. Step
    For other functionalities like accessibility and events, create an index.tsx file packages/themed/src/components/Circle/index.tsx and export it.
import { Root } from "./styled-components"
const Circle = (props) => {
return <Root>{props.children}</Root>
  1. Step
    And then export from packages/themed/src/components/index.tsx
// other components
export * from "./Circle"
  1. Step
    Now we will define theme for Circle inside packages/config/src/theme/Circle.ts.
import { createStyle } from "@gluestack-style/react"
export const Circle = createStyle({
alignItems: "center",
justifyContent: "center",
borderRadius: "$full",
overflow: "hidden",
variants: {
size: {
large: {
width: 100,
height: 100,
  1. Step
    And then export from packages/config/src/index.ts
// other components
export * from "./Circle"

Step 3: Test Your Package

Now you can import and test your component.
import { Circle } from "@myapp/components"
export default () => <Circle size="large" />

Step 4: Publish Your Package

Now you can publish your design system as a package from packages/themed and theme package from packages/config.

Step 5: Integrate it in Your App

Once published, you can use @myapp/components in your app you need add it to your package.json and update your configuration.


Update next.config.js:
/** @type {import('next').NextConfig} */
const { withGluestackUI } = require("@gluestack/ui-next-adapter")
const nextConfig = {
reactStrictMode: true,
transpilePackages: ["@myapp/components", "@myapp/config"],
module.exports = withGluestackUI(nextConfig)


No need to update any config for Expo.
Note: For production optimization you can have a look here
Edit this page on GitHub