---
title: Theme Tokens | Theme tokens in gluestack-style
description: gluestack-style uses tokens to store design-related values such as colors, typography, spacing, and more. They are a way of centralizing the values in a single location.
---

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

<Meta title="configuration/Theme Tokens" />

# Theme Tokens

gluestack-style employs tokens to store design-related attributes like colors, typography, spacing, and more. Tokens centralize these values in one location, simplifying the task of updating and maintaining your application's design. We recommend trying to follow the [system-ui theme specification](https://github.com/system-ui/theme-specification) as closely as possible.

To utilize theme tokens, create a config object in gluestack-style.config.ts/js at your app's root level, including all the design tokens you intend to use in your application. Here is an example of a theme object:

```js
import { createConfig } from 'gluestack-style/react';

const config = createConfig({
  aliases: {
    // ...
  },
  tokens: {
    colors: {
      primary: 'blue',
      secondary: 'green',
      text: 'black',
      background: 'white',
    },
    fonts: {
      body: 'Arial, sans-serif',
      heading: 'Georgia, serif',
    },
    fontSizes: {
      small: '12px',
      medium: '16px',
      large: '20px',
    },
    space: { 0: 0, 1: 4, 2: 8, 4: 16, 8: 32 },
  },
  globalStyle: {
    // ...
  },
} as const);
```

This example's theme object encompasses various properties for colors, fonts, font sizes, and spacing. You can add as many properties as you need, such as typography, border radius, shadows, etc.

## Using tokens

After defining your theme, you can pass it as a prop to the StyledProvider component for use in your components.

Here is an example of how you can use theme tokens in a component:

```jsx
const StyledButton = styled(Pressable, {
  backgroundColor: '$primary',
  padding: '$2',
});
```

## Using Aliases

gluestack-style supports the use of `aliases` to make it easier to work with theme tokens and other configuration options.Aliases enable shorthand names for theme tokens or configuration values, simplifying their references in your code.
To use aliases, you need to define them in your config file, such as **`gluestack-style.config.js`** in your config object. Here is an example of how you can define aliases in a config file:

```js
import { createConfig } from 'gluestack-style/react';

const config = createConfig({
  aliases: {
    bg: 'backgroundColor',
    p: 'padding',
    m: 'margin',
    // ...
  },
  tokens: {
    // ...
  },
  globalStyle: {
    // ...
  },
} as const);
```

In this example, we have defined aliases for **`backgroundColor`**, **`padding`**, **`margin`**. Once the aliases are defined, you can use them in your component styles instead of the full property name.

Here is an example of how you can use aliases in your component:

```jsx
const StyledButton = styled(Pressable, {
  $bg: 'blue',
  $p: '8px',
});
```

## Property mapping

For an enhanced developer experience, token types are automatically mapped to CSS Properties.

```js
const borderStyles = 'borderStyles';
const borderWidths = 'borderWidths';
const colors = 'colors';
const mediaQueries = 'mediaQueries';
const opacity = 'opacity';
const fonts = 'fonts';
const fontSizes = 'fontSizes';
const fontWeights = 'fontWeights';
const letterSpacings = 'letterSpacings';
const lineHeights = 'lineHeights';
const radii = 'radii';
const shadows = 'shadows';
const space = 'space';
const transitions = 'transitions';
const zIndices = 'zIndices';
export const propertyTokenMap = {
  gap: space,
  gridGap: space,
  columnGap: space,
  gridColumnGap: space,
  rowGap: space,
  gridRowGap: space,
  inset: space,
  insetBlock: space,
  insetBlockEnd: space,
  insetBlockStart: space,
  insetInline: space,
  insetInlineEnd: space,
  insetInlineStart: space,
  margin: space,
  marginTop: space,
  marginRight: space,
  marginBottom: space,
  marginLeft: space,
  marginBlock: space,
  marginBlockEnd: space,
  marginBlockStart: space,
  marginInline: space,
  marginInlineEnd: space,
  marginInlineStart: space,

  marginHorizontal: space,
  marginVertical: space,
  padding: space,
  paddingTop: space,
  paddingRight: space,
  paddingBottom: space,
  paddingLeft: space,

  paddingBlock: space,
  paddingBlockEnd: space,
  paddingBlockStart: space,
  paddingInline: space,
  paddingInlineEnd: space,
  paddingInlineStart: space,

  paddingHorizontal: space,
  paddingVertical: space,
  paddingStart: space,
  paddingEnd: space,

  top: space,
  right: space,
  bottom: space,
  left: space,
  scrollMargin: space,
  scrollMarginTop: space,
  scrollMarginRight: space,
  scrollMarginBottom: space,
  scrollMarginLeft: space,
  scrollMarginX: space,
  scrollMarginY: space,
  scrollMarginBlock: space,
  scrollMarginBlockEnd: space,
  scrollMarginBlockStart: space,
  scrollMarginInline: space,
  scrollMarginInlineEnd: space,
  scrollMarginInlineStart: space,
  scrollPadding: space,
  scrollPaddingTop: space,
  scrollPaddingRight: space,
  scrollPaddingBottom: space,
  scrollPaddingLeft: space,
  scrollPaddingX: space,
  scrollPaddingY: space,
  scrollPaddingBlock: space,
  scrollPaddingBlockEnd: space,
  scrollPaddingBlockStart: space,
  scrollPaddingInline: space,
  scrollPaddingInlineEnd: space,
  scrollPaddingInlineStart: space,
  shadowRadius: space,
  elevation: space,

  fontSize: fontSizes,

  background: colors,
  backgroundColor: colors,
  backgroundImage: colors,
  borderImage: colors,
  border: colors,
  borderBlock: colors,
  borderBlockEnd: colors,
  borderBlockStart: colors,
  borderBottom: colors,
  borderBottomColor: colors,
  borderColor: colors,
  borderInline: colors,
  borderInlineEnd: colors,
  borderInlineStart: colors,
  borderLeft: colors,
  borderLeftColor: colors,
  borderRight: colors,
  borderRightColor: colors,
  borderTop: colors,
  borderTopColor: colors,
  caretColor: colors,
  color: colors,
  columnRuleColor: colors,
  fill: colors,
  outline: colors,
  outlineColor: colors,
  stroke: colors,
  textDecorationColor: colors,
  shadowColor: colors,

  shadowOpacity: opacity,

  // Media Query
  condition: mediaQueries,

  fontFamily: fonts,

  fontWeight: fontWeights,

  lineHeight: lineHeights,

  letterSpacing: letterSpacings,

  blockSize: space,
  minBlockSize: space,
  maxBlockSize: space,
  inlineSize: space,
  minInlineSize: space,
  maxInlineSize: space,
  width: space,
  minWidth: space,
  maxWidth: space,
  height: space,
  minHeight: space,
  maxHeight: space,
  flexBasis: space,
  gridTemplateColumns: space,
  gridTemplateRows: space,

  borderWidth: borderWidths,
  borderTopWidth: borderWidths,
  borderRightWidth: borderWidths,
  borderBottomWidth: borderWidths,
  borderLeftWidth: borderWidths,

  borderStyle: borderStyles,
  borderTopStyle: borderStyles,
  borderRightStyle: borderStyles,
  borderBottomStyle: borderStyles,
  borderLeftStyle: borderStyles,

  borderRadius: radii,
  borderTopLeftRadius: radii,
  borderTopRightRadius: radii,
  borderBottomRightRadius: radii,
  borderBottomLeftRadius: radii,

  boxShadow: colors,
  textShadow: shadows,

  transition: transitions,

  zIndex: zIndices,
};
```
