Config v5

The recommended Tamagui configuration gives you a complete design system, flexible theme generation, Tailwind aligned shorthands, multiple animation drivers, and easy customization.

V5 builds on v4 with more colors, theme helpers, and expanded media queries. Migration from v4 is straightforward - see what’s changed.

First install the config package:

yarn
npm
bun
pnpm
yarn add @tamagui/config
Copy

What’s Different from v4

• Animations not bundled - Import separately from v5-css, v5-rn, v5-reanimated, or v5-motion. See Choosing an Animation Driver.
• Media query naming - 2xl/2xs → xxl/xxs/xxxs. Max queries use kebab-case: max2Xl → max-xxl.
• styleCompat: 'react-native' - flex now uses flexBasis: 0 by default (v4 used 'legacy' with flexBasis: auto).
• defaultPosition not set - Defaults to browser static instead of v4’s 'relative'. You can still set it in your config.

• More color themes: gray, blue, red, yellow, green, orange, pink, purple, teal, neutral (v4 had blue, red, yellow, green, black, white)
• createV5Theme helper for easy theme customization
• Height-based media queries: heightXXXS, heightXXS, heightXS, etc.
• pointerTouch media query for touch device detection
• Color utilities: adjustPalette, adjustPalettes for transforming palettes
• Radix Colors v3 with improved accessibility (v4 used legacy Radix)

To restore v4 behavior while using v5:

tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v5'
import { animations } from '@tamagui/config/v5-css'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations,
  settings: {
    ...defaultConfig.settings,
    styleCompat: 'legacy',
    defaultPosition: 'relative',
  },
})
Copy

Update media query names in your code: $2xl → $xxl, $2xs → $xxs, $max2Xl → $max-xxl.

Choosing an Animation Driver

V5 provides separate entry points for different animation drivers, so you only bundle what you need:

tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v5'
import { animations } from '@tamagui/config/v5-css'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations,
})
Copy

Available animation drivers:

• @tamagui/config/v5-css - CSS animations (smallest bundle, great for web)
• @tamagui/config/v5-motion - Motion animations (spring physics, smooth)
• @tamagui/config/v5-rn - React Native Animated API
• @tamagui/config/v5-reanimated - Reanimated (best native performance)

For apps targeting both web and native, you can use different animation drivers per platform:

tamagui.config.ts
import { defaultConfig } from '@tamagui/config/v5'
import { animations as animationsCSS } from '@tamagui/config/v5-css'
import { animations as animationsReanimated } from '@tamagui/config/v5-reanimated'
import { createTamagui, isWeb } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations: isWeb ? animationsCSS : animationsReanimated,
})
Copy

This gives you CSS animations on web (smaller bundle, better performance) and Reanimated on native (smooth 60fps animations).

All v5 animation drivers include these preset animations:

Timing animations (fixed duration):

Spring animations (physics-based):

Customizing Themes with createV5Theme

The createV5Theme function lets you customize the default v5 themes. The easiest way to add or change colors is using @tamagui/colors which provides Radix color palettes:

tamagui.config.ts
import { createV5Theme, defaultChildrenThemes, defaultConfig } from '@tamagui/config/v5'
import { cyan, cyanDark, amber, amberDark } from '@tamagui/colors'
import { createTamagui } from 'tamagui'

const themes = createV5Theme({
  childrenThemes: {
    // include defaults (blue, red, green, yellow, etc.)
    ...defaultChildrenThemes,
    // add new colors
    cyan: { light: cyan, dark: cyanDark },
    amber: { light: amber, dark: amberDark },
  },
})

export const config = createTamagui({
  ...defaultConfig,
  themes,
})
Copy

Or use only the colors you need:

tamagui.config.ts
import { createV5Theme } from '@tamagui/config/v5'
import { blue, blueDark, gray, grayDark } from '@tamagui/colors'

// minimal theme with just blue and gray
const themes = createV5Theme({
  childrenThemes: {
    blue: { light: blue, dark: blueDark },
    gray: { light: gray, dark: grayDark },
  },
})
Copy

For a more muted look, use the subtle variant which has desaturated colors:

tamagui.config.ts
import { defaultConfig, themes } from '@tamagui/config/v5-subtle'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  themes,
})
Copy

Use adjustPalette to transform colors with a callback function. The callback receives each color’s HSL values and its 1-based index (1-12):

tamagui.config.ts
import {
  adjustPalette,
  adjustPalettes,
  defaultChildrenThemes,
  createV5Theme,
} from '@tamagui/config/v5'

// adjust a single palette - desaturate and lighten
const mutedBlue = adjustPalette(blue, (hsl, i) => ({
  ...hsl,
  s: hsl.s * 0.7,
  l: Math.min(100, hsl.l * 1.1),
}))

// adjust multiple palettes at once with adjustPalettes
const mutedThemes = adjustPalettes(defaultChildrenThemes, {
  // 'default' applies to all colors not explicitly listed
  default: {
    light: (hsl, i) => ({ ...hsl, s: hsl.s * 0.8 }),
    dark: (hsl, i) => ({ ...hsl, s: hsl.s * 0.6, l: hsl.l * 0.9 }),
  },
  // override specific colors
  yellow: {
    light: (hsl) => ({ ...hsl, s: hsl.s * 0.5 }),
    dark: (hsl, i) => ({ ...hsl, s: hsl.s * (i <= 4 ? 0.3 : 0.8) }),
  },
  // skip adjustment for specific colors
  gray: undefined,
})

const themes = createV5Theme({ childrenThemes: mutedThemes })
Copy

The callback receives:

• hsl - object with h (hue 0-360), s (saturation 0-100), l (lightness 0-100)
• i - 1-based index in the palette (1-12)

Use the index to apply different adjustments to background colors (1-4), mid-tones (5-8), and foreground colors (9-12).

Theme Values

V5 themes include a rich set of color values accessible via $theme-* tokens.

Every theme includes 12 base colors that shift based on the theme:

<View bg="$color1" />  // Lightest in light mode, darkest in dark mode
<View bg="$color6" />  // Mid-range
<View bg="$color12" /> // Darkest in light mode, lightest in dark mode
Copy

Standard semantic values that adapt to each theme:

• background, backgroundHover, backgroundPress, backgroundFocus
• color, colorHover, colorPress, colorFocus
• borderColor, borderColorHover, borderColorPress, borderColorFocus
• placeholderColor, outlineColor

Foreground and background colors with opacity variants. The naming uses the opacity value without the decimal point (e.g., 01 = 10%, 0025 = 2.5%).

• color01 (10%), color0075 (7.5%), color005 (5%), color0025 (2.5%), color002 (2%), color001 (1%)
• background01 (10%), background0075 (7.5%), background005 (5%), background0025 (2.5%), background002 (2%), background001 (1%)
• background02 (20%), background04 (40%), background06 (60%), background08 (80%)

Always available regardless of theme, with opacity variants:

• white, white0 (transparent), white02, white04, white06, white08
• black, black0 (transparent), black02, black04, black06, black08
• white1-white12, black1-black12 (12-step scales)

Pre-tuned shadow opacities (black) for light and dark modes:

• shadow1 through shadow8 (light shadows are subtler, dark are stronger)
• shadowColor - Default shadow color for the theme

Pre-tuned highlight opacities (white) for light and dark modes:

• highlight1 through highlight8 (matching shadow scale, useful for glows/overlays)

All color themes expose their full 12-step scale:

<View bg="$blue5" />
<Text color="$red11" />
<View borderColor="$green7" />
Copy

Available scales: gray1-12, blue1-12, red1-12, green1-12, yellow1-12, orange1-12, pink1-12, purple1-12, teal1-12

The neutral scale maintains sufficient contrast on both light and dark backgrounds - useful for text or UI that needs to work regardless of theme:

• neutral1-neutral12

Every theme includes an inverted accent scale for contrast elements:

• accent1-accent12 - Inverted palette (light colors in dark mode, vice versa)
• accentBackground, accentColor - Quick access to accent bg/fg

<Button theme="accent">Primary Action</Button>
<View bg="$accentBackground" color="$accentColor" />
Copy

Color Themes

V5 includes these color themes by default:

• Grayscale: gray, neutral
• Colors: blue, green, red, yellow, orange, pink, purple, teal
• Fixed: black, white (generated from base palettes, don’t change between light/dark)

Each color theme has 12 steps following the Radix Colors  pattern.

Use any color theme with the theme prop:

<Button theme="blue">Blue button</Button>
<Card theme="purple">Purple card</Card>
Copy

Access individual color values in any theme:

<View bg="$orange5" borderColor="$teal7" />
<Text color="$pink11" />
Copy

Templates

V5 includes default templates that control how theme values map to palette indices. Available templates: base, surface1, surface2, surface3, alt1, alt2, inverse.

For more details on how templates work, see the Creating Custom Themes Guide.

Component Themes

V5 keeps component themes because they solve a hard problem — how do you change the theme of an entire area (like from dark to dark_green) but have the components inside it still keep their relative shades?

One of the great things in Tamagui is being able to set component themes, and sub-themes, and have an entire area of your UI re-theme and look perfect.

We’d exported just having the ability to set a default theme, like “surface1 => 4”, but then if you try and re-theme a component to green, that would conflict. For example, if you made your default <Button theme="surface3" />, then if someone uses it <Button theme="green" /> now it’s green, but not the Button green that is typically stronger than your base green.

So for now we’ve left them on! We do want to move away from component themes in general as they can be tricky to understand. But the benefits are also strong, and until we find a great solution we’re leaving them. You can always set componentThemes: false in your createV5Themes function to turn it off.

Settings

V5 config includes these default settings:

Media Queries

V5 includes an expanded set of media queries with height-based, max-width, and min-width variants.

The $sm through $xxl breakpoints match Tailwind CSS exactly (640, 768, 1024, 1280, 1536), making it easy to work across both ecosystems. The smaller breakpoints ($xxxs, $xxs, $xs) provide finer control below 640px, which is especially useful for container queries where you need granularity at smaller sizes.

Shorthands

V5 uses the same Tailwind-aligned shorthands as v4. See the v4 config docs for the full list.

Tree Shaking Themes

Production Optimization - Theme JS can grow to 20KB or more. Since Tamagui can hydrate themes from CSS variables, you can remove the themes JS from your client bundle for better Lighthouse scores.

This works because Tamagui generates CSS variables for all theme values. On the client, it reads these from the DOM instead of needing the JS object.

tamagui.config.ts
import { defaultConfig, themes } from '@tamagui/config/v5'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  // only load themes on server - client hydrates from CSS
  // for non-One Vite apps, use import.meta.env.SSR instead
  themes: process.env.VITE_ENVIRONMENT === 'client' ? ({} as typeof themes) : themes,
})
Copy

Summary: v4 to v5 Migration Checklist

1. Add animations import - v5 doesn’t bundle animations:

   import { animations } from '@tamagui/config/v5-css'
   Copy

2. Update media query names - 2xl → xxl, 2xs → xxs, max2Xl → max-xxl
3. Review flex behavior - v5 uses flexBasis: 0 by default (React Native style)
4. Review position - v5 doesn’t set defaultPosition (defaults to static)
5. Review theme colors - v5 uses Radix Colors v3 with slightly different values