Quick Config

Easy config and themes with @tamagui/config/v4

Config v4 simplifies configuration, generates much more useful themes, and adds a new helper function for generating your own theme suite called createThemes.

The new defaultConfig is the easiest way to get going:

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

export const config = createTamagui(defaultConfig)

type CustomConfig = typeof config

// ensure types work
declare module 'tamagui' {
  interface TamaguiCustomConfig extends CustomConfig {}
}

It gives you a robust suite of themes, a few shorthands that mostly align with Tailwind, and default settings that prevent bugs.

If you like it but want to make some changes, you can copy and paste the source code into your app and customize to your taste.

Custom Themes

If you want to learn to create your own custom theme suite rather than use the included defaults, check out the Creating Custom Themes Guide.

wwwwwwwwwwwwwwwwwww

Default Configuration

Themes

Let's see how defaultThemes is defined:

themes.ts
import * as Colors from '@tamagui/colors'
import { createThemes, defaultComponentThemes } from '@tamagui/config/v4'

const darkPalette = [
  '#050505',
  '#151515',
  '#191919',
  '#232323',
  '#282828',
  '#323232',
  '#424242',
  '#494949',
  '#545454',
  '#626262',
  '#a5a5a5',
  '#fff',
]

const lightPalette = [
  '#fff',
  '#f8f8f8',
  'hsl(0, 0%, 96.3%)',
  'hsl(0, 0%, 94.1%)',
  'hsl(0, 0%, 92.0%)',
  'hsl(0, 0%, 90.0%)',
  'hsl(0, 0%, 88.5%)',
  'hsl(0, 0%, 81.0%)',
  'hsl(0, 0%, 56.1%)',
  'hsl(0, 0%, 50.3%)',
  'hsl(0, 0%, 42.5%)',
  'hsl(0, 0%, 9.0%)',
]

const lightShadows = {
  shadow1: 'rgba(0,0,0,0.04)',
  shadow2: 'rgba(0,0,0,0.08)',
  shadow3: 'rgba(0,0,0,0.16)',
  shadow4: 'rgba(0,0,0,0.24)',
  shadow5: 'rgba(0,0,0,0.32)',
  shadow6: 'rgba(0,0,0,0.4)',
}

const darkShadows = {
  shadow1: 'rgba(0,0,0,0.2)',
  shadow2: 'rgba(0,0,0,0.3)',
  shadow3: 'rgba(0,0,0,0.4)',
  shadow4: 'rgba(0,0,0,0.5)',
  shadow5: 'rgba(0,0,0,0.6)',
  shadow6: 'rgba(0,0,0,0.7)',
}

const extraColors = {
  black1: darkPalette[0],
  black2: darkPalette[1],
  black3: darkPalette[2],
  black4: darkPalette[3],
  black5: darkPalette[4],
  black6: darkPalette[5],
  black7: darkPalette[6],
  black8: darkPalette[7],
  black9: darkPalette[8],
  black10: darkPalette[9],
  black11: darkPalette[10],
  black12: darkPalette[11],
  white1: lightPalette[0],
  white2: lightPalette[1],
  white3: lightPalette[2],
  white4: lightPalette[3],
  white5: lightPalette[4],
  white6: lightPalette[5],
  white7: lightPalette[6],
  white8: lightPalette[7],
  white9: lightPalette[8],
  white10: lightPalette[9],
  white11: lightPalette[10],
  white12: lightPalette[11],
}

const generatedThemes = createThemes({
  componentThemes: defaultComponentThemes,
  
  base: {
    palette: {
      dark: darkPalette,
      light: lightPalette,
    },

    // for values we don't want being inherited onto sub-themes
    extra: {
      light: {
        ...Colors.blue,
        ...Colors.green,
        ...Colors.red,
        ...Colors.yellow,
        ...lightShadows,
        ...extraColors,
        shadowColor: lightShadows.shadow1,
      },
      dark: {
        ...Colors.blueDark,
        ...Colors.greenDark,
        ...Colors.redDark,
        ...Colors.yellowDark,
        ...darkShadows,
        ...extraColors,
        shadowColor: darkShadows.shadow1,
      },
    },
  },

  // inverse accent theme
  accent: {
    palette: {
      dark: lightPalette,
      light: darkPalette,
    },
  },

  childrenThemes: {
    blue: {
      palette: {
        dark: Object.values(Colors.blueDark),
        light: Object.values(Colors.blue),
      },
    },
    red: {
      palette: {
        dark: Object.values(Colors.redDark),
        light: Object.values(Colors.red),
      },
    },
    yellow: {
      palette: {
        dark: Object.values(Colors.yellowDark),
        light: Object.values(Colors.yellow),
      },
    },
    green: {
      palette: {
        dark: Object.values(Colors.greenDark),
        light: Object.values(Colors.green),
      },
    },
  },
})

export type TamaguiThemes = typeof generatedThemes

/**
 * This is an optional production optimization: themes JS can get to 20Kb or more.
 * Tamagui has ~1Kb of logic to hydrate themes from CSS, so you can remove the JS.
 * So long as you server render your Tamagui CSS, this will save you bundle size:
 */
export const themes: TamaguiThemes =
  process.env.TAMAGUI_ENVIRONMENT === 'client' &&
  process.env.NODE_ENV === 'production'
    ? {}
    : (generatedThemes as any)

This will generate a large amount of themes for you, including some default component themes. If you don't want components like Button and Input to have custom styling, you can remove componentThemes and they will default to not having any color styling (you can further add the unstyled prop to remove all styling).

We will be adding more to this shortly with a visual guide to your themes.

Settings

Props

mediaQueryDefaultActive

See Media

defaultFont

body

fastSchemeChange

On iOS, leverages DynamicColorIOS for fast light/dark theme changes.

shouldAddPrefersColorThemes

Generates CSS for prefers-color-scheme, so even with JS off you have proper light/dark styling.

allowedStyleDescriptions

More strict than just a string, but still allows web-only style descriptions like vh, vw.

themeClassNameOnRoot

Defaults to putting your root theme className onto the root html tag so you can use your CSS variables on your body tag.

onlyAllowShorthands

For any shorthand defined, remove the types for the longhand.

maxDarkLightNesting

To save CSS and bundle size, only allow light and dark to nest once, instead prefer using black/white themes included below the root.

Media

The new media queries in v4 are also more simplified and aligned to Tailwind:

Props

2xl

maxWidth: 1536

xl

maxWidth: 1280

lg

maxWidth: 1024

md

maxWidth: 768

sm

maxWidth: 640

xs

maxWidth: 460

2xs

maxWidth: 340

Every media query defaults to true to align with mobile-first design .

Shorthands

Config v4 has fewer shorthands, and aligns shorthands to Tailwind for familiarity

Props

text

textAlign

b

bottom

bg

backgroundColor

content

alignContent

flex

flexDirection

grow

flexGrow

items

alignItems

justify

justifyContent

l

left

m

margin

maxH

maxHeight

maxW

maxWidth

mb

marginBottom

minH

minHeight

minW

minWidth

ml

marginLeft

mr

marginRight

mt

marginTop

mx

marginHorizontal

my

marginVertical

p

padding

pb

paddingBottom

pl

paddingLeft

pr

paddingRight

pt

paddingTop

px

paddingHorizontal

py

paddingVertical

r

right

rounded

borderRadius

select

userSelect

self

alignSelf

shrink

flexShrink

t

top

z

zIndex

Tokens

Tokens are defined as:

export const size = {
  $0: 0,
  '$0.25': 2,
  '$0.5': 4,
  '$0.75': 8,
  $1: 20,
  '$1.5': 24,
  $2: 28,
  '$2.5': 32,
  $3: 36,
  '$3.5': 40,
  $4: 44,
  $true: 44,
  '$4.5': 48,
  $5: 52,
  $6: 64,
  $7: 74,
  $8: 84,
  $9: 94,
  $10: 104,
  $11: 124,
  $12: 144,
  $13: 164,
  $14: 184,
  $15: 204,
  $16: 224,
  $17: 224,
  $18: 244,
  $19: 264,
  $20: 284,
}

export const space = {
  // ... space is the same as size, but also defines "negative" values for every size, like:
  '$-1': -20,
}

export const zIndex = {
  0: 0,
  1: 100,
  2: 200,
  3: 300,
  4: 400,
  5: 500,
}

export const radius = {
  0: 0,
  1: 3,
  2: 5,
  3: 7,
  4: 9,
  true: 9,
  5: 10,
  6: 16,
  7: 19,
  8: 22,
  9: 26,
  10: 34,
  11: 42,
  12: 50,
}

Note that color tokens aren't defined, instead we are just using themes.

Fonts

Only a body and heading font are exported, which both use "system" font families:

Props

web

-apple-system, system-ui, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif

native

System

You can create your own system font using the exported createSystemFont helper.

Configuration

Tokens

Edit this page on GitHub.