Tamagui Best Practices
Tamagui v1.x patterns beyond fundamentals: Config v4, compiler optimization, compound components, and gotchas.
Reference Files — Read Before Writing Code
| Context | File | What it covers |
|---|---|---|
| Dialog, Sheet, modal overlays | @DIALOG_PATTERNS.md | Adapt component, accessibility |
| Form, Input, Label, validation | @FORM_PATTERNS.md | zod integration |
| Animations, transitions | @ANIMATION_PATTERNS.md | drivers, enterStyle/exitStyle |
| Popover, Tooltip, Select | @OVERLAY_PATTERNS.md | overlay primitives |
| Compiler optimization | @COMPILER_PATTERNS.md | what the compiler can/cannot flatten |
| Design tokens, theming | @DESIGN_SYSTEM.md | palette, token structure |
Config v4
Minimal setup with @tamagui/config/v4. Add styleCompat: 'react-native' for new projects to align flexBasis with React Native behavior:
import { defaultConfig } from '@tamagui/config/v4'
import { createTamagui } from 'tamagui'
export const config = createTamagui({
...defaultConfig,
settings: { ...defaultConfig.settings, styleCompat: 'react-native' },
})
declare module 'tamagui' {
interface TamaguiCustomConfig extends typeof config {}
}For custom themes use createThemes with palette/accent/childrenThemes — see @DESIGN_SYSTEM.md.
Compiler Optimization Rules
- Use
styled()variants instead of inline conditionals — dynamic values break flattening. - Avoid
style={{...}}with variables; use variant props instead. - The
contextpattern (createStyledContext) disables compiler flattening — use for higher-level components (Button, Card), not primitives.
// BAD — breaks compiler
<View backgroundColor={isDark ? '$gray1' : '$gray12'} />
// GOOD — use variants
const Box = styled(View, {
variants: {
dark: { true: { backgroundColor: '$gray1' }, false: { backgroundColor: '$gray12' } },
},
})styled() vs Inline
styled(): reusable components, variant-driven behavior, compiler-optimizable primitives.- Inline props: one-off layout adjustments on already-styled components.
- Always use
as constonvariantsobjects (TypeScript limitation until inferred const generics).
Key Gotchas
Prop order determines override priority — props after a spread cannot be overridden by callers:
// width is locked; backgroundColor can be overridden
<View backgroundColor="$red10" {...props} width={200} />Variant order matters — later props win:
<Component scale={3} huge /> // scale = 3 (scale listed first)
<Component huge scale={3} /> // scale = 2 (huge overrides, comes first in variants)Use .styleable() when wrapping styled components — preserves variant inheritance:
const CorrectWrapper = StyledText.styleable((props, ref) => (
<StyledText ref={ref} {...props} />
))accept prop for non-standard token resolution (SVG fill/stroke, contentContainerStyle):
const StyledSVG = styled(SVG, {}, { accept: { fill: 'color', stroke: 'color' } as const })Import consistency — tamagui, @tamagui/core, and @tamagui/button are different packages; pick one approach per project.
Never mix RN StyleSheet with Tamagui — StyleSheet values don't resolve tokens.
Platform branching for Dialog/Sheet — use Adapt instead of Platform.OS checks (see @DIALOG_PATTERNS.md).
Quick Reference
Config v4 shorthands: bg backgroundColor, p padding, m margin, w width, h height, br borderRadius
Media breakpoints: $xs 660px, $sm 800px, $md 1020px, $lg 1280px, $xl 1420px
Animation drivers: css (web, default), react-native-reanimated (native, required)
Token $ prefix: use in props (color="$color"), omit in theme definitions ({color: palette[11]})
Fetching Current Docs
curl -sL "https://tamagui.dev/docs/core/configuration.md"
curl -sL "https://tamagui.dev/llms.txt" # full index