Tokens

Accessing and using tokens

Tamagui lets you create tokens using createTokens, which is then passed to the createTamagui 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 createTamagui, you can access your tokens from anywhere using getTokens:

import { getTokens } from '@tamagui/core'

getTokens().size.small

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 Tamagui 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

Tamagui 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.

Using tokens with components

When using styled or any Tamagui 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:

How tokens apply to attributes

Size

width, height, minWidth, minHeight, maxWidth, maxHeight

zIndex

Radius

borderRadius, borderTopLeftRadius, borderTopRightRadius, borderBottomLeftRadius, borderBottomRightRadius

Color

color, backgroundColor, borderColor, borderBottomColor, borderTopColor, borderLeftColor, borderRightColor

Space

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:

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, Stack } from '@tamagui/core'

export const MyStack = styled(Stack, {
  width: '$icon.small'
})

Configuration

View & Text

Edit this page on GitHub.