Configuration

Set up tokens, themes, fonts, media queries, shorthands, settings, and sizing.

Configuration connects your tokens, themes, media queries, animations, shorthands, settings, and sizing to every Tamagui component.

Start with @tamagui/config/v6 for default tokens, Tailwind-aligned shorthands, and themes.

Create a tamagui.config.ts file:

yarnnpmbunpnpm
yarn add @tamagui/config

tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v6'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  media: {
    ...defaultConfig.media,
    // add your own media queries here, if wanted
  },
})

type OurConfig = typeof config

declare module 'tamagui' {
  interface TamaguiCustomConfig extends OurConfig {}
}

Pass the config export to a TamaguiProvider at the root of your app:

import { TamaguiProvider, html } from 'tamagui'
import { config } from './tamagui.config.ts'

export default () => (
  <TamaguiProvider config={config}>
    <html.div margin="4" />
  </TamaguiProvider>
)

That is a working setup. Import tamagui.config.ts once, near the root. Other files reach the config through style props and hooks like useMedia and useTheme.

This guide imports from tamagui. If you only use the style library, swap the imports for @tamagui/core, which is a strict subset.

The shape of createTamagui

createTamagui takes one object. Every key is optional. Here is a complete config written from scratch, without the v6 preset, to show each concern in one place:

tamagui.config.ts
import { createFont, createTamagui, createTokens, isWeb } from 'tamagui'

// fonts group size, lineHeight, weight, and letterSpacing per family.
// createFont fills any keys you leave out of lineHeight, weight, or letterSpacing.
const systemFont = createFont({
  family: isWeb ? 'Helvetica, Arial, sans-serif' : 'System',
  size: {
    1: 12,
    2: 14,
    3: 15,
  },
  lineHeight: {
    // numeric config values are absolute pixels, so 1 resolves to 22
    2: 22,
  },
  weight: {
    1: '300',
    3: '600',
  },
  letterSpacing: {
    1: 0,
    2: -1,
  },
  // native only: picks the font file by weight and style
  face: {
    300: { normal: 'InterLight', italic: 'InterItalic' },
    600: { normal: 'InterBold' },
  },
})

// tokens work like CSS variables: set once, available everywhere.
// keys can be anything. the tamagui components expect 1 through 10.
const size = {
  0: 0,
  1: 5,
  2: 10,
  // ...
}

export const tokens = createTokens({
  size,
  space: { ...size, '-1': -5, '-2': -10 },
  radius: { 0: 0, 1: 3 },
  zIndex: { 0: 0, 1: 100, 2: 200 },
  color: {
    white: '#fff',
    black: '#000',
  },
})

const config = createTamagui({
  fonts: {
    heading: systemFont,
    body: systemFont,
  },

  tokens,

  // themes can change anywhere in the tree with <Theme name="dark" />.
  // dark_blue is a sub-theme of dark, reached with <Theme name="blue" /> inside it.
  themes: {
    light: {
      bg: '#f2f2f2',
      color: tokens.color.black,
    },
    dark: {
      bg: '#111',
      color: tokens.color.white,
    },
    dark_blue: {
      bg: 'darkblue',
      color: tokens.color.white,
    },
  },

  // media queries become style prop keys, useMedia keys, and group style keys
  media: {
    sm: { maxWidth: 860 },
    gtSm: { minWidth: 860 + 1 },
    short: { maxHeight: 820 },
    hoverable: { hover: 'hover' },
    touchable: { pointer: 'coarse' },
  },

  // <html.div m={10} /> becomes <html.div margin={10} />
  // as const keeps the keys literal for onlyAllowShorthands
  shorthands: {
    px: 'paddingHorizontal',
    f: 'flex',
    m: 'margin',
    w: 'width',
  } as const,

  settings: {
    disableSSR: true,
    allowedStyleValues: 'somewhat-strict-web',
  },
})

type AppConfig = typeof config

// if you publish your own design system, put its package name here instead of tamagui
declare module 'tamagui' {
  interface TamaguiCustomConfig extends AppConfig {}

  // optional: types for named group styling modifiers such as group-hover/card:
  interface TypeOverride {
    groupNames(): 'card' | 'header' | 'sidebar'
  }
}

export default config

If using the compiler, your tamagui.config.ts is parsed at build-time. For this reason, we recommend keeping it relatively simple. Avoid importing heavy dependencies.

Where each concern lives

Each key of createTamagui has its own page. The sections below say what the key does and where to read more.

TamaguiProvider

TamaguiProvider mounts the config at the root of your app. It also owns how the generated CSS reaches the page in production, and the option to drop theme JS from the client bundle. See TamaguiProvider.

Tokens

Tokens are static values with a name. They compile to CSS variables on web and are available to every style prop. Create them with createTokens and pass them under tokens. The categories size, space, radius, zIndex, and color map to specific style properties, and you can add any category of your own. See Tokens for how tokens resolve, custom categories, and the px helper.

Font tokens

Fonts are tokens with structure. Each family carries its own size, line height, weight, and letter spacing scales, created with createFont. Android needs the face map to select font files by weight. See Fonts.

Themes

Themes sit one level above tokens. They hold values that change per subtree, most often colors, and components read them by key. Sub-themes such as dark_blue fall back to their parent. Custom variables merge into every base theme and can be redefined for any subtree. See Defining themes for the config shape, Themes for usage, and Creating themes for generating full theme suites.

TamaguiProvider

Edit this page on GitHub.

Configuration

The shape of createTamagui

Where each concern lives

TamaguiProvider

Tokens

Font tokens

Themes

Media

Animations

Shorthands

Settings

Sizing