gui/apps/gui.hanzo.ai/data/docs/core/tokens.mdx

---
title: Tokens
description: Accessing and using tokens
---

Gui lets you create tokens using `createTokens`, which is then passed to the `createGui` function as part of the [configuration](/docs/core/configuration) object.

## Getting Tokens

For example, if you define some tokens:

```tsx
const tokens = createTokens({
  size: {
    small: 10,
  },
})
```

After you pass that into `createGui`, you can access your tokens from anywhere using `getTokens`:

```tsx
import { getTokens } from '@hanzogui/core'

getTokens().size.small
```

or

```tsx
getTokens().size['$small']
```

If you'd like just an object containing the prefixed (starting with `$`) or non-prefixed values, you can use the `prefixed` option:

```tsx
// only non-$
getTokens({ prefixed: false }).size.small
// only $
getTokens({ prefixed: true })['$size'].small
```

What is returned is of type `Variable`, which is what Gui turns all tokens and theme values into internally in order to give them CSS variable names, as well as other things:

```tsx
getTokens().size.small.val // returns 10
getTokens().size.small.variable // returns something like (--size-small), which matches the CSS rule inserted
```

Gui has some helpers that make working with variables easier, which are documented in [Exports](/docs/core/exports), namely [`getVariable`](/docs/core/exports#getvariable) which will return the CSS variable on web, but raw value on native, and `getVariableValue` which always returns the raw value.

### Color Tokens as Fallback Values for Themes

Color tokens are available as fallback values when you access a theme. So when you `useTheme()` and then access a value that isn't in the theme, it will check for a `tokens.color` with the matching name.

Think of it this way:

- Tokens are static and are your base values.
- Themes are dynamic, they can change in your React tree, and live above tokens.

If you are confused by Gui themes, don't be. You can avoid them altogether, or avoid learning them until later. Instead, you can just build your app using regular style props and leave out themes altogether. Or, simply use a `light` and a `dark` theme if you want light and dark mode in your app, but avoid using any nested themes.

## Using Tokens with Components

When using `styled` or any Gui component like `Stack`, you can access tokens directly. Just like with `useTheme`, it will first look for a theme value that matches, and if not it will fall back to a token.

Tokens are automatically applied to certain properties. For example, `size` tokens are applied to width and height. And of course `radius` to borderRadius.

Here's how they all apply:

<PropsTable
  title="How tokens apply to attributes"
  data={[
    {
      name: 'Size',
      description: 'width, height, minWidth, minHeight, maxWidth, maxHeight',
    },
    {
      name: 'zIndex',
      description: 'zIndex',
    },
    {
      name: 'Radius',
      description:
        'borderRadius, borderTopLeftRadius, borderTopRightRadius, borderBottomLeftRadius, borderBottomRightRadius',
    },
    {
      name: 'Color',
      description:
        'color, backgroundColor, borderColor, borderBottomColor, borderTopColor, borderLeftColor, borderRightColor',
    },
    {
      name: 'Space',
      description: 'All properties not matched by the above.',
    },
  ]}
/>

## Specific Tokens

As of version 1.34, you can also define any custom token values you'd like:

```tsx
const tokens = createTokens({
  // ...other tokens
  icon: {
    small: 16,
    medium: 24,
    large: 32,
  },
})
```

And then access them using the new "specific tokens" syntax:

```tsx
export default () => (
  <Stack
    // access with the category first:
    width="$icon.small"
  />
)
```

This, like all token values, works the same with `styled`:

```tsx
import { styled, View } from '@hanzogui/core'

export const MyView = styled(View, {
  width: '$icon.small',
})
```

When creating custom tokens, you can use the `px` helper to ensure values get proper pixel units on web while remaining as raw numbers on native:

```tsx
import { createTokens, px } from '@hanzogui/core'

const tokens = createTokens({
  customSize: {
    small: px(100), // → "100px" on web, 100 on native
    medium: px(200),
    large: px(300),
  },
  opacity: {
    low: 0.25, // → 0.25 (unitless on both platforms)
    medium: 0.5,
    high: 0.75,
  },
})
```

<Notice theme="blue">
  The predefined token categories like `size`, `space`, and `radius` automatically add
  pixel units where appropriate, so you don't need to use the `px` helper for them.
</Notice>