--- name: mobile-ui-components-tamagui description: Tamagui universal UI - styled(), tokens, themes, optimizing compiler, responsive media queries, animations, Sheet/Dialog components --- # Tamagui Universal UI Patterns > **Quick Guide:** Tamagui provides universal styled components for React Native and web with an optimizing compiler that flattens components to native primitives. Use `styled()` with variants for component APIs, `$`-prefixed tokens for consistent spacing/color, theme nesting for light/dark modes, and the `transition` prop for animations. The compiler extracts static styles to CSS on web and hoists style objects on native -- but only when props are deterministic at build time. --- ## CRITICAL: Before Using This Skill > **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants) **(You MUST use `$`-prefixed token values in style props (`$4`, `$color.blue`) -- raw pixel values bypass the token system and break theme consistency)** **(You MUST keep the `transition` prop present in JSX when using animations -- conditionally removing it causes expensive hook teardown; pass `null` to disable instead)** **(You MUST add `as const` to variant definition objects -- without it TypeScript cannot infer variant prop types correctly)** **(You MUST use `Adapt` for responsive Dialog-to-Sheet behavior -- manual Platform.OS branching breaks compiler optimization and misses breakpoint changes)** --- **Auto-detection:** Tamagui, tamagui, styled(), createTamagui, createTokens, createTheme, XStack, YStack, ZStack, SizableText, Paragraph, Theme, useTheme, useMedia, $sm, $md, $lg, enterStyle, exitStyle, hoverStyle, pressStyle, transition prop, Sheet, Dialog, Adapt, GetProps, TamaguiProvider, @tamagui/core, @tamagui/config **When to use:** - Building universal React Native + web UIs that share components across platforms - Creating design-system-driven components with typed token scales and theme variants - Optimizing render performance via compiler flattening (styled components to native divs/Views) - Implementing responsive layouts with media query style props (`$sm`, `$gtMd`) - Adding enter/exit/hover/press animations with swappable animation drivers - Building adaptive overlays (Dialog on desktop, Sheet on mobile) with `Adapt` **When NOT to use:** - Web-only projects where a web-native styling solution is simpler - Apps needing pixel-perfect custom native UI beyond what React Native Views provide - Performance-critical animations that need direct native driver control beyond Tamagui's animation abstraction **Key patterns covered:** - `styled()` with typed variants (spread, boolean, functional) and `GetProps` type extraction - Token system (`createTokens`, `$`-prefix references, category-to-property mapping) - Theme hierarchy (base, sub-themes, component themes, `useTheme`, dark/light switching) - Optimizing compiler (flattening, CSS extraction, what prevents optimization) - Responsive styles with media query props and `useMedia` hook - Animation system with `transition` prop, `enterStyle`/`exitStyle`, and driver selection - Sheet and Dialog with `Adapt` for responsive overlay behavior **Detailed Resources:** - [examples/core.md](examples/core.md) - styled(), variants, tokens, themes, compiler optimization - [examples/responsive-animations.md](examples/responsive-animations.md) - Media queries, useMedia, animation drivers, enter/exit styles - [examples/overlays.md](examples/overlays.md) - Sheet, Dialog, Adapt pattern - [reference.md](reference.md) - Decision frameworks, token-to-property mapping, migration notes --- ## Philosophy Tamagui solves the universal UI problem: write components once that render optimally on both React Native and web. The key insight is that **compile-time analysis can eliminate the runtime cost of a universal abstraction**. **Core principles:** 1. **Tokens are the source of truth** -- spacing, color, radius, and font values flow from `createTokens` through themes to components via `$`-prefixed references. Raw values bypass the system. 2. **Themes override tokens contextually** -- themes are scoped CSS variables that change within React subtrees. Missing theme keys resolve upward to parent themes, then to tokens. 3. **The compiler rewards deterministic styles** -- static props, token references, and spread variants can be flattened to native primitives. Dynamic expressions, ternaries on non-media values, and function render props prevent optimization. 4. **Animation drivers are swappable** -- CSS transitions for web, Reanimated for native, configured once in `createTamagui`. Component code stays identical. 5. **Adapt replaces platform branching** -- `Adapt` transforms Dialog to Sheet at breakpoints without manual `Platform.OS` checks. **Tamagui v2** is the current stable release. Key changes from v1: `animation` prop renamed to `transition`, config v5 with Tailwind-aligned breakpoints, expanded color system with Radix Colors v3, native portals for Sheet/Dialog/Popover, and headless/unstyled component variants. --- ## Core Patterns ### Pattern 1: styled() with Typed Variants `styled()` extends a base component with default styles and type-safe variants. Use `GetProps` to export the derived prop type. ```tsx import { GetProps, styled, View, Text } from "@tamagui/core"; export const Card = styled(View, { name: "Card", backgroundColor: "$background", borderRadius: "$4", padding: "$4", borderWidth: 1, borderColor: "$borderColor", variants: { size: { "...size": (val, { tokens }) => ({ padding: tokens.size[val] ?? val, }), }, elevated: { true: { elevation: "$2" }, }, } as const, }); export type CardProps = GetProps; ``` **Why good:** `name` property enables component-specific themes (`dark_Card`), spread variant `...size` maps all size tokens automatically, `as const` preserves literal types for variant inference, `GetProps` keeps prop type in sync with the component ```tsx // BAD: raw values bypass token system export const Card = styled(View, { padding: 16, // raw pixel -- not theme-aware borderRadius: 8, // should be $4 or a radius token backgroundColor: "#fff", // hardcoded -- breaks dark mode }); ``` **Why bad:** raw values bypass token resolution and theme switching, hardcoded colors break in dark mode, no connection to design system See [examples/core.md](examples/core.md) for full variant patterns including boolean, functional, and nested `styled(styled())`. --- ### Pattern 2: Token System and Theme Hierarchy Tokens define the design scale. Themes override token values within React subtrees. Components reference `$`-prefixed keys that resolve to the active theme, falling back to tokens. ```tsx // Token reference in JSX Themed text // Theme nesting -- inner Theme applies as "dark_green" {/* uses dark_green theme */} ``` **Why good:** `$background` resolves from active theme (light or dark), nested Theme composes name automatically (`dark` + `green` = `dark_green`), missing keys in sub-theme fall back to parent theme then to tokens See [examples/core.md](examples/core.md) for `createTokens`, `createTheme`, theme definition patterns, and `useTheme` hook usage. --- ### Pattern 3: Compiler Optimization The compiler flattens styled components to native primitives (`div` on web, `View` on native) and extracts atomic CSS. This only works when styles are **deterministic at build time**. ```tsx // GOOD: compiler can flatten -- all values are static tokens // GOOD: media query props are compiler-optimized // BAD: dynamic ternary prevents flattening // BAD: function render prop deoptimizes } /> ``` **Key rule:** Static token values, spread variants, and media query props are compiler-friendly. JavaScript expressions, ternaries on runtime values, and function render props force runtime evaluation. See [examples/core.md](examples/core.md) for what the compiler can/cannot optimize and how to structure code for maximum flattening. --- ### Pattern 4: Responsive Styles with Media Queries Use `$`-prefixed media query props for responsive styles. The compiler extracts these to CSS `@media` rules on web, eliminating runtime overhead. ```tsx ``` **Why good:** mobile-first base styles, media props override progressively, compiler extracts to CSS @media rules on web (zero JS runtime) See [examples/responsive-animations.md](examples/responsive-animations.md) for `useMedia` hook, config breakpoints, and height-based queries. --- ### Pattern 5: Animations with transition Prop The `transition` prop references a named animation from your config. Combine with `enterStyle`, `exitStyle`, `hoverStyle`, and `pressStyle` for declarative animations. ```tsx ``` **Why good:** declarative animation states, driver-agnostic (CSS on web, Reanimated on native), SSR-safe enterStyle **Critical:** always keep `transition` in JSX -- pass `null` to disable, never conditionally omit the prop (causes expensive hook teardown). See [examples/responsive-animations.md](examples/responsive-animations.md) for driver configuration, `AnimatePresence`, and per-property `animateOnly`. --- ### Pattern 6: Sheet and Dialog with Adapt Use `Adapt` to render Dialog as a Sheet on touch devices at smaller breakpoints. This avoids manual `Platform.OS` branching and responds to viewport changes. ```tsx Title Description ``` **Why good:** single component tree handles both desktop dialog and mobile sheet, `Adapt.Contents` injects Dialog.Content into Sheet.Frame, breakpoint-driven not platform-driven See [examples/overlays.md](examples/overlays.md) for controlled Sheet, snap points, ScrollView inside Sheet, and Dialog state preservation. --- ## Decision Framework ### When to Use styled() vs Inline Props ``` Is this a reusable component with variants or a semantic name? ├─ YES → styled() with name, variants, defaultVariants └─ NO → Is this one-off layout? ├─ YES → Inline props on XStack/YStack () └─ NO → styled() if you want component themes or compiler naming ``` ### Animation Driver Selection ``` Platform target? ├─ Web only → @tamagui/animations-css (smallest bundle, CSS transitions) ├─ Native only → @tamagui/animations-reanimated (worklet-based, spring physics) ├─ Universal → Configure per-platform in createTamagui │ ├─ Web: CSS or Motion driver │ └─ Native: Reanimated or React Native driver └─ Simple transitions? → @tamagui/animations-react-native (no extra dependency) ``` ### Overlay Component Choice ``` Need bottom sheet on mobile? ├─ YES → Is there also a desktop version? │ ├─ YES → Dialog + Adapt + Sheet (single component tree) │ └─ NO → Sheet standalone └─ NO → Dialog (portal-based overlay) ``` --- ## RED FLAGS **High Priority Issues:** - Using raw pixel values (`padding: 16`) instead of tokens (`padding: "$4"`) -- bypasses theme system, breaks consistency across platforms - Conditionally removing the `transition` prop from JSX -- causes expensive spring hook teardown/setup; pass `null` to disable instead - Missing `as const` on variant definition objects -- TypeScript infers `string` instead of literal union types, losing autocomplete and type safety - Using `Platform.OS` branching for Dialog vs Sheet -- use `Adapt` instead, which responds to breakpoints and is compiler-optimized - Hardcoded color strings (`"#fff"`, `"#000"`) in styled components -- breaks dark/light theme switching; use `$background`, `$color` **Medium Priority Issues:** - Not setting `name` on styled components that need component-level themes -- without `name`, Tamagui cannot look up component-specific theme variants like `dark_Card` - Using JavaScript ternaries for responsive styles instead of media query props -- prevents compiler CSS extraction, adds runtime cost - Nesting `styled(styled())` without `.styleable()` when wrapping with a functional component -- variant merging breaks silently - Importing from `tamagui` instead of `@tamagui/core` when you only need the core -- pulls in the entire UI kit unnecessarily **Gotchas & Edge Cases:** - **Theme nesting is name-based:** `` resolves to `dark_green`, not just `green`. The sub-theme must be defined as `dark_green` in your config. - **`Object.groupBy` on `useMedia()` result fails:** The proxied object from `useMedia` is not iterable -- use direct key access (`media.sm`) only. - **`Dialog.Sheet` does not preserve state** when transitioning between Sheet and Portal modes. Lift state above the Dialog if persistence is needed. - **Spread variants (`...size`) only match top-level token categories** -- custom nested token groups require functional variants instead. - **`elevation` prop** generates both shadow props (iOS) and elevation (Android) on native, but translates to `box-shadow` on web. Differences in shadow appearance across platforms are expected. - **Config v5 changed flex defaults:** With `styleCompat: 'react-native'`, `flex` uses `flexBasis: 0` (not `auto`). Without it, web defaults apply. - **The Moti animation driver is deprecated** -- switch to `@tamagui/animations-reanimated` (same API, fewer dependencies). - **String-to-boolean coercion in config** -- if parsing env vars for config flags, the string `"false"` is truthy in JavaScript. Use explicit comparison (`val === "true"`) not coercion. --- ## CRITICAL REMINDERS > **All code must follow project conventions in CLAUDE.md** **(You MUST use `$`-prefixed token values in style props (`$4`, `$color.blue`) -- raw pixel values bypass the token system and break theme consistency)** **(You MUST keep the `transition` prop present in JSX when using animations -- conditionally removing it causes expensive hook teardown; pass `null` to disable instead)** **(You MUST add `as const` to variant definition objects -- without it TypeScript cannot infer variant prop types correctly)** **(You MUST use `Adapt` for responsive Dialog-to-Sheet behavior -- manual Platform.OS branching breaks compiler optimization and misses breakpoint changes)** **Failure to follow these rules will break theme consistency, cause animation performance issues, lose type safety on variants, and produce non-adaptive overlays.**