Tokens

Hanzo GUI lets you create tokens using createTokens, which is then passed to the createGui function as part of the configuration object.

Getting Tokens

For example, if you define some tokens:

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

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

import { getTokens } from '@hanzogui/core'

getTokens().size.small

or

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:

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

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

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

Hanzo GUI has some helpers that make working with variables easier, which are documented in Exports, namely 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 Hanzo 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 Hanzo 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:

Specific Tokens

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

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

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

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

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

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:

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,
  },
})