Tokens

Tokens give style props typed names for shared design values such as space, size, radius, color, and z-index.

Create them with createTokens, then pass them to createTamagui as part of the configuration object.

Getting tokens

For example, if you define some tokens:

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

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

import { getTokens } from '@tamagui/core'

getTokens().size.small
Copy

or

getTokens().size['small']
Copy

getTokens takes no options in v3. Tokens are keyed by their unprefixed name, so size.small is the only spelling you need. The prefixed option that used to return a $-keyed copy is removed.

getTokens() returns Variable objects, which Tamagui uses to manage values and CSS variable names:

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

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.

v3 token behavior

The default v3 configs do not export true token keys. Component defaults still resolve to the default size, and that default size is 4.

// before v3
<Button size="$true" />

// v3
<Button size="4" />
Copy

@tamagui/get-token also no longer performs runtime token stepping. getSize, getSpace, and getRadius resolve the same key you pass in. The old stepTokenUpOrDown, getTokenRelative, and options such as shift, bounds, and excludeHalfSteps are removed.

// before v3
const padding = getSize(size, { shift: -2 })

// v3
const padding = getVariableValue(getSize(size)) * 0.6
Copy

If you need a smaller or larger named token, choose that token explicitly. If you need proportional sizing, multiply the resolved numeric value.

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.

You can skip themes at first and build with style props and tokens alone, adding light and dark themes only when you need them. Avoid nested themes until you need them.

Using tokens with components

When using styled or any Tamagui component like View, 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 apply automatically to matching properties. size tokens apply to width and height, radius to borderRadius:

Specific tokens

You can also define custom token categories of your own:

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

And then access them using the “specific tokens” syntax:

export default () => (
  <html.div
    // access with the category first:
    width="icon.small"
  />
)
Copy

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

import { styled, View } from '@tamagui/core'

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

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 '@tamagui/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,
  },
})
Copy

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.