Settings

Strictness, SSR, theme class placement, and other createTamagui settings.

Pass a settings object to createTamagui to control type strictness, SSR behavior, flex behavior, units, and how themes reach the DOM.

tamagui.config.ts
export const config = createTamagui({
  // ...
  settings: {
    disableSSR: true,
    allowedStyleValues: 'somewhat-strict-web',
    defaultFont: 'body',
  },
})

@tamagui/config/v6 sets sensible values for all of these. Spread defaultConfig.settings and override the keys you need.

Options

Props

disableSSR

boolean

For SSR compatibility on the web, Tamagui renders once with the mediaQueryDefaultActive values for every media query, then renders again with the real values so hydration matches the server. Set this to true to skip the first pass and render with live media state right away, which is what client-only (SPA) apps want. See Server Rendering for the ClientOnly component and related hooks.

defaultFont

string

The key of the font given to createTamagui that text falls back to when it sets no fontFamily, so "body" or "heading".

mediaQueryDefaultActive

Record<string, boolean>

Which media queries count as active on the first render. Used for SSR.

addThemeClassName

false | 'html' | 'body'

Where to put the root theme className on web. Styling <body> with theme CSS variables needs the class on body or above. When false, the class goes on the element TamaguiProvider renders.

selectionStyles

(theme) => ({ backgroundColor: Variable | string; color: Variable | string })

Generates ::selection styles for text selection on the web.

shouldAddPrefersColorThemes

boolean

Default:

true

Generates prefers-color-scheme media queries for your light and dark themes. Increases total CSS size.

onlyAllowShorthands

boolean

Removes the types for the long-form version of every shorthand you define. See Shorthands.

styleValueSyntax

'string' | 'object'

Default:

undefined

Restrict conditional style values to one syntax. Flat values accept both the string form (bg="red hover:blue") and the object form (bg={{ default: 'red', hover: 'blue' }}). Setting this narrows the types to one form, makes the runtime warn on the other in development, and tells tamagui generate-prompt and the skills to only show that form.

allowedStyleValues

AllowedStyleValuesSetting

Controls type validation of single-token style values. See below. Run tamagui check --strict to validate conditional payloads against the project config too.

styleCompat

'legacy' | 'react-native' | 'web'

Default:

'web'

Which flex expansion semantics to follow where Yoga and CSS differ. Numeric lineHeight values are ratios in every mode.

remBaseFontSize

number

Default:

16

Base font size for rem calculations on native. On web, browsers use the root font size.

defaultPosition

'static' | 'relative'

Default:

'static'

Default position value for all Tamagui components.

onlyShorthandStyleProps

boolean

Removes the longhand border, outline, and shadow props (borderWidth, outlineWidth, shadowColor, and the rest) from the types, encouraging the combined border, outline, and boxShadow props instead. Type-level only.

fastSchemeChange

boolean

On iOS, returns color values as DynamicColorIOS so light and dark switches skip a re-render. The defaultTheme you pass to TamaguiProvider must match the current system color scheme.

optimizeFor

'updates' | 'first-render'

Default:

'updates' on web, 'first-render' on native

Chooses the render performance tradeoff. "updates" tracks which theme and media keys each component reads so changes re-render only their consumers, at a small per-component first-render cost. "first-render" skips per-key tracking for the fastest initial render. Theme and media changes still apply, but re-render coarsely. This is a startup-level setting. Do not change it at runtime.

allowedStyleValues

Controls which values the types accept for token-backed style props:

false (default): any string, or number for styles that accept numbers
strict: only tokens for any token-enabled property
strict-web: same as strict, plus web-only values like auto and inherit
somewhat-strict: tokens, or:
- for space and size: percentage strings or numbers
- for radius: numbers
- for zIndex: numbers
- for color: named colors or rgba and hsla strings
somewhat-strict-web: same as somewhat-strict, plus web-only values

Pass one value for every category, or an object to set each category on its own:

type AllowedValueSetting =
  | boolean
  | 'strict'
  | 'somewhat-strict'
  | 'strict-web'
  | 'somewhat-strict-web'

type AllowedStyleValuesSetting =
  | AllowedValueSetting
  | {
      space?: AllowedValueSetting
      size?: AllowedValueSetting
      radius?: AllowedValueSetting
      zIndex?: AllowedValueSetting
      color?: AllowedValueSetting
    }

Environment variables

A few behaviors are set with environment variables rather than settings. Your bundler can then drop the code paths you do not use. On web, use the Tamagui Vite or Next.js plugin, or define them in your own bundler config. On native the extra size is small enough not to matter.

Props

TAMAGUI_TARGET

'web' | 'native'

Which platform the bundle runs on. The Vite and Next.js plugins set it to web. Native builds set it to native on their own.

TAMAGUI_CSS_VARIABLE_PREFIX

string

Prefix added to every CSS variable Tamagui generates on web. Use it to avoid collisions with another library's custom properties.

TAMAGUI_CSS_LAYER

string

Wraps all generated CSS in a named @layer so other stylesheets can order themselves against it.

TAMAGUI_DISABLE_NO_THEME_WARNING

'1'

Silences the development warning when a component renders without any theme. Set it when you use Tamagui without themes on purpose.

Shorthands

Sizing

Edit this page on GitHub.