# Tamagui - Core Patterns

> styled() components, variants, tokens, themes, and compiler optimization. See [SKILL.md](../SKILL.md) for decision guidance and red flags.

---

## Pattern 1: styled() with Variants

### Basic Component with Boolean and Spread Variants

```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: {
      // Spread variant: maps all size tokens automatically
      "...size": (val, { tokens }) => ({
        padding: tokens.size[val] ?? val,
        borderRadius: tokens.radius[val] ?? val,
      }),
    },
    elevated: {
      true: {
        elevation: "$2",
        shadowColor: "$shadowColor",
      },
      false: {
        elevation: "$0",
      },
    },
    transparent: {
      true: {
        backgroundColor: "transparent",
        borderWidth: 0,
      },
    },
  } as const, // REQUIRED for TypeScript variant inference

  defaultVariants: {
    elevated: false,
  },
});

export type CardProps = GetProps<typeof Card>;
```

**Why good:** `name: "Card"` enables component themes (`dark_Card`), `...size` maps token scale automatically, `as const` preserves literal types, `GetProps` derives props from the styled definition, `defaultVariants` provides typed defaults

### Usage

```tsx
<Card size="$4" elevated>
  <SizableText size="$3">Card content</SizableText>
</Card>

<Card size="$2" transparent>
  <SizableText>Transparent card</SizableText>
</Card>
```

---

### Functional Variant with Token Access

```tsx
export const Badge = styled(View, {
  name: "Badge",
  paddingHorizontal: "$2",
  paddingVertical: "$1",
  borderRadius: "$10",

  variants: {
    // Functional variant: receives value + utilities
    status: (val: "success" | "warning" | "error", { theme }) => {
      const colorMap = {
        success: theme.green10,
        warning: theme.yellow10,
        error: theme.red10,
      } as const;
      return {
        backgroundColor: colorMap[val]?.val,
      };
    },
  } as const,
});
```

---

### Composing styled(styled()) and .styleable()

When wrapping a styled component in a functional component (for hooks, logic, etc.), use `.styleable()` to preserve variant merging:

```tsx
const StyledButton = styled(View, {
  name: "Button",
  backgroundColor: "$background",
  paddingHorizontal: "$4",
  paddingVertical: "$2",
  borderRadius: "$3",
  alignItems: "center",
  justifyContent: "center",
  cursor: "pointer",

  variants: {
    variant: {
      primary: { backgroundColor: "$blue10" },
      secondary: { backgroundColor: "$gray5" },
      ghost: { backgroundColor: "transparent" },
    },
  } as const,
});

// .styleable() preserves styled() behavior through functional wrapper
export const Button = StyledButton.styleable<{ loading?: boolean }>(
  ({ loading, children, ...props }, ref) => {
    return (
      <StyledButton ref={ref} opacity={loading ? 0.6 : 1} {...props}>
        {loading ? <Spinner /> : children}
      </StyledButton>
    );
  },
);

// Further composition still works
export const PrimaryButton = styled(Button, {
  variant: "primary",
});
```

**Why good:** `.styleable()` maintains the styled component contract (variants, theme lookups, compiler optimization) through the functional wrapper. Without it, `styled(Button, ...)` cannot merge variants.

---

### Semantic HTML via render Prop (Web)

```tsx
// String render: compiler-optimized, outputs <button> instead of <div>
export const NativeButton = styled(View, {
  render: "button",
  tag: "button",
  cursor: "pointer",
  padding: "$3",
  borderRadius: "$2",
  backgroundColor: "$background",
});

// Runtime override
<Card render="article">
  <SizableText>Semantic article card</SizableText>
</Card>;
```

**Why good:** string `render` prop is compiler-optimized (unlike function render), produces semantic HTML for accessibility, no deoptimization penalty

---

## Pattern 2: Token System

### Defining Tokens with createTokens

```tsx
import { createTokens } from "tamagui";

export const tokens = createTokens({
  size: {
    0: 0,
    1: 4,
    2: 8,
    3: 12,
    4: 16,
    5: 20,
    6: 24,
    8: 32,
    10: 40,
    true: 16, // default size when no value specified
  },
  space: {
    0: 0,
    1: 4,
    2: 8,
    3: 12,
    4: 16,
    5: 20,
    6: 24,
    8: 32,
    true: 16,
    "-1": -4,
    "-2": -8, // negative space for overlaps
  },
  radius: {
    0: 0,
    1: 4,
    2: 8,
    3: 12,
    4: 16,
    10: 9999, // pill shape
    true: 8,
  },
  zIndex: {
    0: 0,
    1: 100,
    2: 200,
    5: 500,
  },
  color: {
    white: "#fff",
    black: "#000",
    gray1: "#f8f8f8",
    gray5: "#999",
    gray10: "#333",
  },
});
```

**Key points:** numeric keys (1-10) recommended for Tamagui UI kit compatibility, `true` key provides default when no size specified, negative space tokens enable overlap patterns, all keys auto-prefixed with `$` when used in components.

### Token Access in Components

```tsx
// In JSX -- $ prefix resolves from tokens/theme
<YStack padding="$4" gap="$2" backgroundColor="$background">
  <SizableText size="$5">Token-driven layout</SizableText>
</YStack>;

// Programmatic access
import { getTokens } from "@tamagui/core";
const size4 = getTokens().size[4].val; // 16
const sizeVar = getTokens().size[4].variable; // "--size-4" (CSS variable)
```

---

## Pattern 3: Theme Definition and Switching

### Creating Themes

```tsx
import { createTheme } from "tamagui";

const lightTheme = createTheme({
  background: "#fff",
  backgroundHover: "#f5f5f5",
  backgroundPress: "#eee",
  color: "#000",
  colorHover: "#333",
  borderColor: "#ddd",
  borderColorHover: "#ccc",
  shadowColor: "rgba(0,0,0,0.1)",
  placeholderColor: "#999",
});

const darkTheme = createTheme({
  background: "#111",
  backgroundHover: "#1a1a1a",
  backgroundPress: "#222",
  color: "#fff",
  colorHover: "#eee",
  borderColor: "#333",
  borderColorHover: "#444",
  shadowColor: "rgba(0,0,0,0.5)",
  placeholderColor: "#666",
});

// Sub-themes: dark_blue inherits from dark, overrides specific keys
const darkBlueTheme = createTheme({
  ...darkTheme,
  background: "#0a1628",
  borderColor: "#1a3a5c",
});
```

### Using Themes in the App

```tsx
import { Theme, useTheme, useThemeName } from "tamagui";

// Wrap sections to apply themes
function App() {
  return (
    <Theme name="dark">
      <YStack flex={1} backgroundColor="$background">
        <Header />
        <Theme name="blue">
          {/* Resolves to dark_blue theme */}
          <FeatureSection />
        </Theme>
      </YStack>
    </Theme>
  );
}

// Access theme values programmatically
function CustomComponent() {
  const theme = useTheme();
  const themeName = useThemeName(); // "dark", "dark_blue", etc.

  return (
    <YStack backgroundColor={theme.background.val}>
      <SizableText>Current theme: {themeName}</SizableText>
    </YStack>
  );
}
```

**Why good:** theme nesting composes names automatically, `useTheme()` provides typed access to all theme values, sub-themes only need to override changed keys

---

## Pattern 4: Configuration with createTamagui

### Minimal Config

```tsx
import { createTamagui, createTokens, createFont } from "tamagui";

const bodyFont = createFont({
  family: "Inter, Helvetica, Arial, sans-serif",
  size: { 1: 12, 2: 14, 3: 16, 4: 18, 5: 22, 6: 28 },
  lineHeight: { 1: 18, 2: 20, 3: 24, 4: 26, 5: 30, 6: 36 },
  weight: { 1: "400", 3: "600", 5: "700" },
  letterSpacing: { 1: 0, 3: -0.5 },
});

export const config = createTamagui({
  tokens,
  themes: {
    light: lightTheme,
    dark: darkTheme,
    dark_blue: darkBlueTheme,
  },
  fonts: {
    body: bodyFont,
    heading: bodyFont, // or a separate heading font
  },
  media: {
    sm: { maxWidth: 640 },
    gtSm: { minWidth: 641 },
    md: { maxWidth: 768 },
    gtMd: { minWidth: 769 },
    lg: { maxWidth: 1024 },
    gtLg: { minWidth: 1025 },
    short: { maxHeight: 820 },
    hoverable: { hover: "hover" },
    touchable: { pointer: "coarse" },
  },
  shorthands: {
    px: "paddingHorizontal",
    py: "paddingVertical",
    mx: "marginHorizontal",
    my: "marginVertical",
    f: "flex",
    w: "width",
    h: "height",
    bg: "backgroundColor",
    br: "borderRadius",
  } as const,
});

// Type augmentation for full IDE support
type AppConfig = typeof config;
declare module "tamagui" {
  interface TamaguiCustomConfig extends AppConfig {}
}
```

### Using Default Config as Starting Point

```tsx
import { defaultConfig } from "@tamagui/config/v5";
import { createTamagui } from "tamagui";

export const config = createTamagui({
  ...defaultConfig,
  // Override only what you need
  themes: {
    ...defaultConfig.themes,
    // Add custom themes
    dark_brand: createTheme({
      ...defaultConfig.themes.dark,
      background: "#0a0a2e",
    }),
  },
});
```

**Why good:** `@tamagui/config/v5` provides Tailwind-aligned breakpoints, Radix Colors v3, pre-built animation presets, and a complete theme system out of the box

---

## Pattern 5: Compiler Optimization Guide

### What Gets Flattened

The compiler performs partial evaluation, analyzing styled() calls and JSX usage to flatten components to native primitives.

```tsx
// BEFORE compilation (developer code)
const MyCard = styled(View, {
  name: "MyCard",
  backgroundColor: "$background",
  padding: "$4",
  borderRadius: "$3",
});

<MyCard elevated />;

// AFTER compilation (web output)
// MyCard → <div class="bg-[var(--background)] p-4 rounded-3" />
// Atomic CSS extracted, component tree flattened
```

### Optimizable vs Non-Optimizable Patterns

```tsx
// OPTIMIZABLE: static token, compiler extracts to CSS
<YStack padding="$4" backgroundColor="$background" />

// OPTIMIZABLE: media query props become @media rules
<YStack padding="$2" $gtMd={{ padding: "$4" }} />

// OPTIMIZABLE: boolean variant with static value
<Card elevated />

// OPTIMIZABLE: spread variant with token value
<Card size="$4" />

// NOT OPTIMIZABLE: runtime ternary
<YStack padding={isExpanded ? "$6" : "$2"} />
// Fix: use media queries if screen-size-dependent,
// or accept runtime cost if truly dynamic

// NOT OPTIMIZABLE: function render prop
<Card render={(props, state) => <CustomCard {...props} />} />
// Fix: use string render prop or accept deoptimization

// NOT OPTIMIZABLE: spread from runtime object
<Card {...dynamicStyles} />
```

### Build Configuration

```tsx
// tamagui.build.ts
import type { TamaguiBuildOptions } from "tamagui";

export default {
  config: "./tamagui.config.ts",
  components: ["tamagui"],
  outputCSS: "./public/tamagui.generated.css",
  disableExtraction: process.env.NODE_ENV === "development",
} satisfies TamaguiBuildOptions;
```

**Key points:** compiler is optional (Tamagui works at runtime without it), recommended for production only, generates output in `.tamagui/` (add to `.gitignore`), `disableExtraction` recommended during development for faster HMR.

# Tamagui - Sheet, Dialog, and Adapt

> Overlay components and responsive adaptation. See [SKILL.md](../SKILL.md) for decision guidance.

---

## Pattern 1: Controlled Sheet with Snap Points

Sheet slides up from the bottom. Use snap points to define positions, and `dismissOnSnapToBottom` for swipe-to-close.

```tsx
import { useState } from "react";
import { Button, Sheet, YStack, SizableText } from "tamagui";

const SNAP_POINTS = [85, 50, 25] as const;
const INITIAL_POSITION = 0;

function BottomSheet() {
  const [open, setOpen] = useState(false);
  const [position, setPosition] = useState(INITIAL_POSITION);

  return (
    <>
      <Button onPress={() => setOpen(true)}>Open Sheet</Button>

      <Sheet
        open={open}
        onOpenChange={setOpen}
        snapPoints={SNAP_POINTS}
        snapPointsMode="percent"
        position={position}
        onPositionChange={setPosition}
        dismissOnSnapToBottom
        modal
      >
        <Sheet.Overlay />
        <Sheet.Handle />
        <Sheet.Frame padding="$4">
          <YStack gap="$3">
            <SizableText size="$6">Sheet Title</SizableText>
            <SizableText size="$3" color="$gray10">
              Swipe down to dismiss or snap to different positions.
            </SizableText>
          </YStack>
        </Sheet.Frame>
      </Sheet>
    </>
  );
}
```

**Key points:** `snapPoints` array values go from most visible (85%) to least visible (25%), `snapPointsMode="percent"` interprets values as screen percentage, `dismissOnSnapToBottom` closes when swiped past last snap point, `modal` adds overlay and prevents background interaction.

---

## Pattern 2: Sheet with Scrollable Content

Use `Sheet.ScrollView` instead of a regular ScrollView inside Sheet for proper gesture coordination.

```tsx
function ScrollableSheet({ items }: { items: string[] }) {
  const [open, setOpen] = useState(false);

  return (
    <Sheet
      open={open}
      onOpenChange={setOpen}
      snapPoints={[80]}
      dismissOnSnapToBottom
      modal
    >
      <Sheet.Overlay />
      <Sheet.Handle />
      <Sheet.Frame>
        <YStack padding="$4" paddingBottom="$0">
          <SizableText size="$5">Scrollable Content</SizableText>
        </YStack>
        {/* Sheet.ScrollView coordinates gestures with sheet drag */}
        <Sheet.ScrollView padding="$4">
          <YStack gap="$2">
            {items.map((item) => (
              <YStack
                key={item}
                padding="$3"
                backgroundColor="$background"
                borderRadius="$2"
              >
                <SizableText>{item}</SizableText>
              </YStack>
            ))}
          </YStack>
        </Sheet.ScrollView>
      </Sheet.Frame>
    </Sheet>
  );
}
```

**Why `Sheet.ScrollView`:** a regular ScrollView captures all vertical gestures, preventing the sheet from being dragged down. `Sheet.ScrollView` coordinates scroll and drag gestures so the sheet dismisses when scrolled to top.

---

## Pattern 3: Dialog with Portal

Dialog renders content in a portal above the rest of the app. Use sub-components for semantic structure.

```tsx
import { Button, Dialog, YStack, SizableText, XStack } from "tamagui";

function ConfirmDialog() {
  return (
    <Dialog modal>
      <Dialog.Trigger asChild>
        <Button>Delete Item</Button>
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Overlay
          key="overlay"
          transition="quick"
          enterStyle={{ opacity: 0 }}
          exitStyle={{ opacity: 0 }}
          opacity={0.5}
        />
        <Dialog.Content
          key="content"
          transition="quick"
          enterStyle={{ opacity: 0, scale: 0.95, y: -10 }}
          exitStyle={{ opacity: 0, scale: 0.95, y: -10 }}
          bordered
          elevate
          padding="$4"
          gap="$3"
        >
          <Dialog.Title>Confirm Deletion</Dialog.Title>
          <Dialog.Description>
            This action cannot be undone. Are you sure?
          </Dialog.Description>

          <XStack gap="$3" justifyContent="flex-end">
            <Dialog.Close asChild>
              <Button>Cancel</Button>
            </Dialog.Close>
            <Dialog.Close asChild>
              <Button theme="red">Delete</Button>
            </Dialog.Close>
          </XStack>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}
```

**Key points:** `asChild` on Trigger/Close makes the child element the actual interactive element, `key` props on Overlay and Content enable AnimatePresence exit animations, `bordered elevate` adds border and shadow from theme.

---

## Pattern 4: Dialog with Adapt (Sheet on Mobile)

The primary pattern for responsive overlays. `Adapt` renders Dialog.Content as a Sheet at smaller breakpoints on touch devices.

```tsx
import {
  Adapt,
  Button,
  Dialog,
  Sheet,
  YStack,
  SizableText,
  XStack,
  Input,
} from "tamagui";

function AdaptiveFormDialog() {
  return (
    <Dialog modal>
      <Dialog.Trigger asChild>
        <Button>Edit Profile</Button>
      </Dialog.Trigger>

      {/* On small touch screens, render as bottom sheet */}
      <Adapt when="sm" platform="touch">
        <Sheet modal dismissOnSnapToBottom snapPoints={[85]}>
          <Sheet.Frame padding="$4" gap="$4">
            {/* Adapt.Contents inserts Dialog.Content children here */}
            <Adapt.Contents />
          </Sheet.Frame>
          <Sheet.Overlay />
        </Sheet>
      </Adapt>

      {/* On larger screens / non-touch, render as centered dialog */}
      <Dialog.Portal>
        <Dialog.Overlay
          key="overlay"
          transition="quick"
          enterStyle={{ opacity: 0 }}
          exitStyle={{ opacity: 0 }}
          opacity={0.5}
        />
        <Dialog.Content
          key="content"
          bordered
          elevate
          transition="quick"
          enterStyle={{ opacity: 0, scale: 0.95 }}
          exitStyle={{ opacity: 0, scale: 0.95 }}
          padding="$4"
          gap="$4"
          width={400}
        >
          <Dialog.Title>Edit Profile</Dialog.Title>
          <Dialog.Description>
            Update your display name and bio.
          </Dialog.Description>

          <YStack gap="$3">
            <Input placeholder="Display name" />
            <Input placeholder="Bio" />
          </YStack>

          <XStack gap="$3" justifyContent="flex-end">
            <Dialog.Close asChild>
              <Button>Cancel</Button>
            </Dialog.Close>
            <Dialog.Close asChild>
              <Button theme="active">Save</Button>
            </Dialog.Close>
          </XStack>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}
```

**Why good:** single component tree handles both desktop dialog and mobile sheet, `Adapt.Contents` injects the Dialog.Content children into Sheet.Frame, breakpoint-driven (`when="sm"`) responds to viewport changes (not just initial platform).

**Gotcha:** `Dialog.Sheet` does NOT preserve state when transitioning between Sheet and Portal modes. If your form has input state, lift it above the Dialog component to avoid state loss during adaptation transitions.

---

## Pattern 5: Controlled Dialog with External State

For dialogs that need external open/close control (e.g., from a parent component or store).

```tsx
function ControlledDialog({
  open,
  onOpenChange,
}: {
  open: boolean;
  onOpenChange: (open: boolean) => void;
}) {
  return (
    <Dialog open={open} onOpenChange={onOpenChange} modal>
      <Dialog.Portal>
        <Dialog.Overlay
          key="overlay"
          transition="quick"
          enterStyle={{ opacity: 0 }}
          exitStyle={{ opacity: 0 }}
          opacity={0.5}
        />
        <Dialog.Content
          key="content"
          transition="medium"
          enterStyle={{ opacity: 0, y: -20 }}
          exitStyle={{ opacity: 0, y: -20 }}
          padding="$4"
          gap="$4"
          bordered
          elevate
        >
          <Dialog.Title>Controlled Dialog</Dialog.Title>
          <Dialog.Description>Open state managed by parent.</Dialog.Description>
          <Dialog.Close asChild>
            <Button>Close</Button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}

// Usage: parent manages state
function Parent() {
  const [dialogOpen, setDialogOpen] = useState(false);

  return (
    <>
      <Button onPress={() => setDialogOpen(true)}>Open</Button>
      <ControlledDialog open={dialogOpen} onOpenChange={setDialogOpen} />
    </>
  );
}
```

**Performance tip:** If Dialog is inside a frequently re-rendering list, place only `Dialog.Trigger` inside the list item and lift the Dialog itself to a parent component. Dialog has significant sub-component overhead that should not be multiplied per list item.

# Tamagui - Responsive Styles and Animations

> Media queries, useMedia hook, animation drivers, and enter/exit animations. See [SKILL.md](../SKILL.md) for decision guidance.

---

## Pattern 1: Responsive Styles with Media Query Props

Media query props use `$`-prefixed breakpoint names. Base styles apply at all sizes (mobile-first), overridden progressively at larger breakpoints.

```tsx
import { XStack, YStack, SizableText } from "tamagui";

function ResponsiveLayout() {
  return (
    <XStack
      flexDirection="column"
      padding="$2"
      gap="$2"
      $gtSm={{ flexDirection: "row", padding: "$4", gap: "$4" }}
      $gtLg={{ padding: "$6", gap: "$6" }}
    >
      <YStack
        flex={1}
        backgroundColor="$background"
        padding="$3"
        borderRadius="$3"
      >
        <SizableText size="$4">Panel A</SizableText>
      </YStack>
      <YStack
        flex={1}
        backgroundColor="$background"
        padding="$3"
        borderRadius="$3"
      >
        <SizableText size="$4">Panel B</SizableText>
      </YStack>
    </XStack>
  );
}
```

**Why good:** mobile-first base styles, `$gtSm` and `$gtLg` override progressively, compiler extracts to CSS @media rules on web (zero JS runtime cost)

---

## Pattern 2: useMedia Hook for Conditional Logic

When you need media state in JavaScript logic (not just styles), use `useMedia`. The compiler extracts this to CSS when all usages are deterministic.

```tsx
import { useMedia, YStack, SizableText } from "tamagui";

function AdaptiveContent() {
  const media = useMedia();

  return (
    <YStack padding="$4">
      <SizableText size={media.sm ? "$3" : "$5"}>
        {media.sm ? "Mobile view" : "Desktop view"}
      </SizableText>

      {/* Conditional rendering based on breakpoint */}
      {!media.sm && (
        <YStack>
          <SizableText>Desktop-only sidebar content</SizableText>
        </YStack>
      )}
    </YStack>
  );
}
```

**Gotcha:** the `useMedia()` return object is a Proxy -- you cannot use `Object.keys()`, `for...in`, or the `in` operator on it. Access keys directly: `media.sm`, `media.gtMd`.

---

## Pattern 3: Animation Driver Configuration

Animation drivers are configured in `createTamagui` and swapped per platform. Component code stays identical.

### CSS Driver (Web -- Smallest Bundle)

```tsx
import { createAnimations } from "@tamagui/animations-css";

const animations = createAnimations({
  bouncy: "ease-in 200ms",
  lazy: "ease-out 600ms",
  quick: "ease-in-out 100ms",
  medium: "ease-in-out 300ms",
});
```

### Reanimated Driver (Native -- Spring Physics)

```tsx
import { createAnimations } from "@tamagui/animations-reanimated";

const BOUNCY_DAMPING = 10;
const BOUNCY_STIFFNESS = 100;
const LAZY_DAMPING = 18;
const LAZY_STIFFNESS = 50;
const QUICK_DAMPING = 20;
const QUICK_STIFFNESS = 250;

const animations = createAnimations({
  bouncy: {
    damping: BOUNCY_DAMPING,
    mass: 0.9,
    stiffness: BOUNCY_STIFFNESS,
  },
  lazy: {
    damping: LAZY_DAMPING,
    stiffness: LAZY_STIFFNESS,
  },
  quick: {
    damping: QUICK_DAMPING,
    mass: 1.2,
    stiffness: QUICK_STIFFNESS,
  },
});
```

### Platform-Specific Driver Selection

```tsx
import { createTamagui } from "tamagui";

export const config = createTamagui({
  // ... tokens, themes, media
  animations, // Use CSS on web, Reanimated on native via separate configs
});
```

**Key points:** define the same animation names across drivers for cross-platform compatibility. CSS driver uses easing strings, Reanimated uses spring physics objects. The `@tamagui/animations-moti` driver is deprecated -- use `@tamagui/animations-reanimated` instead (same API, fewer deps).

---

## Pattern 4: Transition Prop and Animation States

The `transition` prop activates animations on a component. Combine with `enterStyle`, `exitStyle`, `hoverStyle`, `pressStyle`, and `focusStyle` for declarative state-based animations.

### Mount Animation with enterStyle

```tsx
import { YStack, SizableText } from "tamagui";

function FadeInCard() {
  return (
    <YStack
      transition="bouncy"
      enterStyle={{ opacity: 0, scale: 0.95, y: -10 }}
      opacity={1}
      scale={1}
      y={0}
      backgroundColor="$background"
      padding="$4"
      borderRadius="$4"
    >
      <SizableText>Fades and scales in on mount</SizableText>
    </YStack>
  );
}
```

**Why good:** SSR-safe (renders base styles on server, animates on client), declarative mount animation without useEffect

### Interaction Animations

```tsx
function InteractiveCard() {
  return (
    <YStack
      transition="quick"
      hoverStyle={{ scale: 1.02, backgroundColor: "$backgroundHover" }}
      pressStyle={{ scale: 0.98, backgroundColor: "$backgroundPress" }}
      focusStyle={{ borderColor: "$borderColorFocus", borderWidth: 2 }}
      backgroundColor="$background"
      padding="$4"
      borderRadius="$4"
      cursor="pointer"
    >
      <SizableText>Hover and press me</SizableText>
    </YStack>
  );
}
```

### Controlling Which Properties Animate

```tsx
<YStack
  transition="bouncy"
  animateOnly={["transform"]}
  hoverStyle={{ scale: 1.05, backgroundColor: "$backgroundHover" }}
>
  {/* Only scale (transform) animates; backgroundColor changes instantly */}
</YStack>
```

---

## Pattern 5: AnimatePresence for Exit Animations

`AnimatePresence` enables exit animations when components unmount. Wrap conditional content and provide `exitStyle`.

```tsx
import { AnimatePresence } from "tamagui";

function ToastNotification({
  visible,
  message,
}: {
  visible: boolean;
  message: string;
}) {
  return (
    <AnimatePresence>
      {visible && (
        <YStack
          key="toast"
          transition="quick"
          enterStyle={{ opacity: 0, y: -20 }}
          exitStyle={{ opacity: 0, y: -20 }}
          opacity={1}
          y={0}
          backgroundColor="$background"
          padding="$3"
          borderRadius="$3"
        >
          <SizableText>{message}</SizableText>
        </YStack>
      )}
    </AnimatePresence>
  );
}
```

**Key points:** `key` prop is required on animated children inside `AnimatePresence`, `exitStyle` defines the animation target on unmount, the animation reverses the enterStyle path by default.

---

## Pattern 6: Disabling Animations Safely

Never conditionally remove the `transition` prop from JSX. Spring-based drivers allocate expensive hooks when the prop exists in the props object.

```tsx
// GOOD: pass null to disable -- no hook teardown
<YStack transition={isAnimating ? "bouncy" : null}>
  <SizableText>Content</SizableText>
</YStack>

// BAD: conditional prop inclusion causes hook teardown/setup
<YStack {...(isAnimating && { transition: "bouncy" })}>
  <SizableText>Content</SizableText>
</YStack>
```

**Why bad:** conditionally spreading the `transition` prop causes the animation driver hooks to mount/unmount on every toggle, which is expensive and can cause visual glitches. Passing `null` keeps the hook mounted but inactive.

If you need to change the animation name after mount, update the component's `key` prop to force a clean remount.