tamagui

Tamagui Skill

Universal React UI framework for web and native. In v3, conditions are flat clauses in the style value, tokens and themes are bare names, and nested condition props such as hoverStyle are removed.

1. Project Configuration First

Before writing Tamagui code, generate or read the project prompt:

npx tamagui generate-prompt

This writes tamagui-prompt.md containing the project's exact token names, theme keys, media breakpoints, shorthands, and components. In an existing app, always inspect and use the project's local component wrappers first before importing from raw packages.

2. Flat Value Grammar

Every conditional style value follows this grammar:

value  := base? clause*
clause := modifier(:modifier)*:payload

• Modifiers chain left-to-right: dark:hover:navy applies when both dark and hover match.
• Payloads extend to the next top-level clause or end of string.
• An empty payload is invalid. Clear a property with none, transparent, initial, or unset.
• Do not author raw transform strings with clauses; use atomic transform props (scale, rotate, x, y).

Supported Modifiers

• Interaction: hover:, press:, focus:, focus-visible:, focus-within:, disabled:
• Media: configured keys such as sm: (min-width), max-sm: (max-width), md:, max-md:
• Theme: dark:, light:, and configured theme names
• Platform: web:, native:, ios:, android:
• Group: group-hover:, group-hover/name:, group-press/name:
• Container: @sm:, @sm/name: (measures nearest query container)
• Presence: enter:, exit: (requires transition=)

Rules

1. No $ sigil: tokens and theme names are bare: bg="background", p="4", not bg="$background".
2. Kebab theme names: built-in theme keys use kebab-case: background-hover, background-press, border-color, border-color-hover, placeholder-color, shadow-color.
3. Numbers are px: a quoted number string p="4" resolves the configured space token. A raw numeric literal p={4} is literal 4px on web or 4 points on native.
4. Specificity precedence ladder: when multiple clauses match, the winner is decided by specificity, not authored order:
   • Platform rank (ios: > native: > bare)
   • Condition count (more conditions win)
   • Category rank: media (1) < container (65) < theme (129) < group (161) < state (225)
   • Authored order breaks exact ties only.
   • A chain supports at most five distinct non-platform conditions.

3. Style Value Syntax

Tamagui supports both string and object syntax. Projects can configure settings.styleValueSyntax to enforce one form.

String Form

import { View } from 'tamagui'

export function Demo() {
  return (
    <View
      bg="background hover:background-hover dark:blue-500"
      p="4 sm:6 max-sm:2"
      w="100% md:50%"
      opacity="web:0.9"
      scale="1 enter:0.9 exit:0.9"
      transition="quick"
    />
  )
}

Object Form

import { View } from 'tamagui'

export function Demo() {
  return (
    <View
      bg={{ default: 'background', hover: 'background-hover', dark: 'blue-500' }}
      p={{ default: '4', sm: '6', 'max-sm': '2' }}
      w={{ default: '100%', md: '50%' }}
      opacity={{ web: 0.9 }}
      scale={{ default: 1, enter: 0.9, exit: 0.9 }}
      transition="quick"
    />
  )
}

4. Shorthands vs Longhands

Check onlyAllowShorthands in tamagui-prompt.md. Under stock v6 it is true, meaning longhand property names are removed from types and will cause type errors. Always author using shorthands:

• p, px, py, pt, pb, pl, pr: padding
• m, mx, my, mt, mb, ml, mr: margin
• w, h, minW, maxW, minH, maxH: dimensions
• bg: background
• color: text color (unshortened in v6)
• rounded: border radius
• items: align items
• justify: justify content

5. Control Sizes

With the v6 config, controls (Button, Input, Select, etc.) accept named sizes: xs, sm, md, lg, xl. The default is md.

import { Button, YStack } from 'tamagui'

export function Buttons() {
  return (
    <YStack gap="2">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </YStack>
  )
}

Use named recipes for control sizes. Legacy token keys such as size="4" remain supported, but use the old height-based sizing model. Spinner has its own small and large sizes.

6. Groups and Containers

Declare group and container as props on the parent, then target them in children:

import { Text, View } from 'tamagui'

export function CardGroup() {
  return (
    <View group="card" container="card">
      <Text color="color group-hover/card:color-focus @sm/card:color">Card title</Text>
    </View>
  )
}

7. Animations and Presence

The v3 animation prop is transition (not animation). For enter and exit transitions, specify enter: and exit: clauses and wrap unmounting components in AnimatePresence with an explicit key:

import { AnimatePresence, View } from 'tamagui'

export function Fade({ visible }: { visible: boolean }) {
  return (
    <AnimatePresence>
      {visible && (
        <View
          key="fade-box"
          opacity="1 enter:0 exit:0"
          scale="1 enter:0.9 exit:0.9"
          transition="quick"
        />
      )}
    </AnimatePresence>
  )
}

8. Removed V2 APIs and Replacements

V2 API	V3 Replacement
hoverStyle={{ ... }}	bg="background hover:background-hover" or bg={{ hover: '...' }}
pressStyle={{ ... }}	press: clause: scale="1 press:0.95"
focusStyle={{ ... }}	focus: clause
enterStyle={{ ... }} / exitStyle={{ ... }}	enter: / exit: clauses with transition="preset"
animation="fast"	transition="fast"
$sm={{ ... }}	sm: clause in style prop: p="2 sm:4"
Sheet.Frame	Sheet.Container and Sheet.Background
Component.styleable(fn)	createStyledHOC(Component, fn)
useProps, useStyle	splitStyleProps, getExpandedShorthand
Select.Item index={i}	index prop removed; use <Select.Item value="val">

9. Packages to Import

• tamagui: styled components with skins (Button, Input, Dialog, Sheet, etc.)
• tamagui/unstyled (@tamagui/ui): unstyled primitives with structural styles only
• @tamagui/core: core styling runtime (View, Text, styled)
• html.*: DOM elements with Tamagui flat value support (html.div, html.span)

10. Verification

Verify styles and syntax with:

npx tamagui check --strict

settings.allowedStyleValues controls type validation of single-token values. Conditional payloads and modifiers also need tamagui check --strict, which loads the project config on a fresh project.

For detailed APIs, read configuration, components, and animations.