Customizing Theme

Customizing the theme in gluestack-ui v2 involves defining a theme configuration and applying it using GluestackUIProvider, enabling you to style your application's visual elements according to your design preferences.

Customizing Tokens

gluestack-ui v2, seamlessly accommodates the default Tailwind CSS theme, allowing users to effortlessly expand and customize it to suit their needs.

gluestack-ui v2 also ships with a set of handpicked default color palette tokens which are mapped separately with each mode. For example, the default color palette for light mode is light and the default color palette for dark mode is dark.

To customize tokens, follow these steps:

Step
1
:
Go to gluestack-ui-provider/config.ts file. Update or add new tokens as per your requirements.

export const config = {
  light: vars({

    ... // other tokens
    //updated '--color-primary-0' value
    '--color-primary-0': '#C0C0C0',

    /* Added a new background color for light mode */
    '--color-background-new': '#BAE7FC',

   /* Add a new token with custom font-size */
   '--custom-font-size': '80'

  }),
  dark: vars({
     ... // other tokens
      /* Added a new background color for dark mode */
    '--color-background-new': '#89D6FA',

   /* Add a new token with custom font-size */
   '--custom-font-size': '80'
  }),
};

Step
2
:
In case you are adding a new color in your config file, you need to update it in the tailwind.config.js file as well.

theme: {
    extend: {
      colors: {
        background: {
          ... // other color values,
          /* Added a new background color */
          new: 'var(--color-background-new)',
        },
      },
        fontSize: {
          ... // other font size values,
          /* Added a new font size token */
         'custom-heading-xl':'var(--custom-font-size)'
      },
    },
    plugins: [],
  },

You can customize all the tokens in config. For a complete list of tokens and default values, please check default Tokens.

By utilizing this approach, you can seamlessly modify the primary color tokens of the theme while maintaining the overall theme configuration intact.

If you want to extend the default tailwind config and add fonts, breakpoints, border radius values, and more, please refer to the tailwindcss documentation.

In order for custom-heading-xl to work, you also will need to pass an additional config for the tva function when defining a component, for Text it will be:

// Text style props are from here https://gluestack.io/ui/docs/components/text (step 3, the one from styles.tsx)
const textStyleProps = {}

//ref @see https://www.tailwind-variants.org/docs/api-reference#config-optional
const config = {
  twMerge: true,
  twMergeConfig: {
    classGroups: {
      "font-size": [
        {
          text: ["custom-heading-xl"],
        },
      ],
    },
  },
}

export const textStyle = tva(...textStyleProps, config)

Another way to solve this is by setting global tailwind-variants config, but it will affect all components. Maybe it's not your case and you want to have a custom font-size only for a specific component/part of the app.