Tamagui

https://tamagui.dev/docs/
Admin
Tamagui is a style library and UI kit for React and React Native with an optimizing compiler that...
Tokens:79,111
Snippets:926
Trust Score:9.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Run Starter-Free App

Source: https://tamagui.dev/docs/guides/create-tamagui-app.md

Commands to navigate into the project directory, install dependencies, and start the local development server for web and native platforms.

```bash
cd myapp
yarn
yarn web # Web local dev
yarn native # Expo local dev (only for `starter-free`)
```

--------------------------------

### Quick Start with createThemes

Source: https://tamagui.dev/docs/guides/theme-builder.md

Use `createThemes` for more control over theme structure while benefiting from automatic palette interpolation and component themes. This example shows a basic setup with light and dark palettes.

```typescript
import { createThemes } from '@tamagui/theme-builder'

export const themes = createThemes({
  base: {
    palette: {
      light: ['#fff', '#000'],
      dark: ['#000', '#fff'],
    },
  },
})
```

--------------------------------

### Install @tamagui/animations-css

Source: https://tamagui.dev/docs/core/animations-css.md

Install the CSS animations driver using yarn.

```bash
yarn add @tamagui/animations-css
```

--------------------------------

### Create New Expo Project

Source: https://tamagui.dev/docs/guides/expo.md

Initialize a new Expo project with a blank TypeScript template. This is the starting point for native setup.

```bash
yarn dlx create-expo-app -t "expo-template-blank-typescript"
```

--------------------------------

### Start Webpack Dev Server

Source: https://tamagui.dev/docs/guides/webpack.md

Command to start the local development server using webpack serve.

```bash
yarn run webpack serve
```

--------------------------------

### Install Webpack and CLI

Source: https://tamagui.dev/docs/guides/webpack.md

Install Webpack and webpack-cli as development dependencies.

```bash
yarn add -D webpack webpack-cli
```

--------------------------------

### Complete Tamagui Configuration Example

Source: https://tamagui.dev/docs/core/configuration.md

A comprehensive example of a tamagui.config.ts file demonstrating the setup of fonts, tokens, themes, media queries, shorthands, and default props. Ensure font faces are defined for Android compatibility.

```tsx
import { createFont, createTamagui, createTokens, isWeb } from 'tamagui'

// To work with the tamagui UI kit styled components (which is optional)
// you'd want the keys used for `size`, `lineHeight`, `weight` and
// `letterSpacing` to be consistent. The `createFont` function
// will fill-in any missing values if `lineHeight`, `weight` or
// `letterSpacing` are subsets of `size`.

const systemFont = createFont({
  family: isWeb ? 'Helvetica, Arial, sans-serif' : 'System',
  size: {
    1: 12,
    2: 14,
    3: 15,
  },
  lineHeight: {
    // 1 will be 22
    2: 22,
  },
  weight: {
    1: '300',
    // 2 will be 300
    3: '600',
  },
  letterSpacing: {
    1: 0,
    2: -1,
    // 3 will be -1
  },
  // (native only) swaps out fonts by face/style
  face: {
    300: { normal: 'InterLight', italic: 'InterItalic' },
    600: { normal: 'InterBold' },
  },
})

// Set up tokens

// The keys can be whatever you want, but if using `tamagui` you'll want 1-10:

const size = {
  0: 0,
  1: 5,
  2: 10,
  // ....
}

export const tokens = createTokens({
  size,
  space: { ...size, '-1': -5, '-2': -10 },
  radius: { 0: 0, 1: 3 },
  zIndex: { 0: 0, 1: 100, 2: 200 },
  color: {
    white: '#fff',
    black: '#000',
  },
})

const config = createTamagui({
  fonts: {
    heading: systemFont,
    body: systemFont,
  },
  tokens,

  themes: {
    light: {
      bg: '#f2f2f2',
      color: tokens.color.black,
    },
    dark: {
      bg: '#111',
      color: tokens.color.white,
    },
  },

  media: {
    sm: { maxWidth: 860 },
    gtSm: { minWidth: 860 + 1 },
    short: { maxHeight: 820 },
    hoverable: { hover: 'hover' },
    touchable: { pointer: 'coarse' },
  },

  // Shorthands
  // Adds <View m={10} /> to <View margin={10} />
  // See Settings section on this page to only allow shorthands
  // Be sure to have `as const` at the end
  shorthands: {
    px: 'paddingHorizontal',
    f: 'flex',
    m: 'margin',
    w: 'width',
  } as const,

  // Change the default props for any styled() component with a name.
  // We are discouraging the use of this and have deprecated it, prefer to use
  // styled() on any component to change its styles.
  defaultProps: {
    Text: {
      color: 'green',
    },
  },
})

type AppConfig = typeof config

// this will give you types for your components
// note - if using your own design system, put the package name here instead of tamagui
declare module 'tamagui' {
  interface TamaguiCustomConfig extends AppConfig {}

  // if you want types for named group styling props (e.g. $group-card-hover),
  // define your group names here:
  interface TypeOverride {
    groupNames(): 'card' | 'header' | 'sidebar'
  }
}

export default config

```

--------------------------------

### Install Tamagui Core

Source: https://tamagui.dev/docs/intro/installation.md

Install the core styling library for Tamagui. Use this if you plan to build your UI components from scratch.

```bash
yarn add @tamagui/core
```

--------------------------------

### Install Webpack Dev Server

Source: https://tamagui.dev/docs/guides/webpack.md

Install webpack-dev-server as a development dependency to run a local development server.

```bash
yarn add -D webpack-dev-server
```

--------------------------------

### Install @tamagui/next-theme

Source: https://tamagui.dev/docs/guides/next-js.md

Install the necessary package for SSR theme support in Next.js.

```bash
yarn add @tamagui/next-theme
```

--------------------------------

### Full Example with createThemes

Source: https://tamagui.dev/docs/guides/theme-builder.md

This comprehensive example demonstrates `createThemes` with custom palettes for base and accent themes, defines child themes for 'blue' and 'red' using imported colors, and sets up grandchild themes and component themes.

```typescript
import { createThemes, defaultComponentThemes } from '@tamagui/theme-builder'
import * as Colors from '@tamagui/colors'

export const themes = createThemes({
  componentThemes: defaultComponentThemes,

  base: {
    palette: {
      light: ['#fff', '#f2f2f2', '#e0e0e0', '#999', '#666', '#333', '#000'],
      dark: ['#000', '#111', '#222', '#666', '#999', '#ccc', '#fff'],
    },
    extra: {
      light: { ...Colors.blue, shadowColor: 'rgba(0,0,0,0.1)' },
      dark: { ...Colors.blueDark, shadowColor: 'rgba(0,0,0,0.4)' },
    },
  },

  accent: {
    palette: {
      light: ['#000', '#333', '#666', '#999', '#ccc', '#eee', '#fff'],
      dark: ['#fff', '#eee', '#ccc', '#999', '#666', '#333', '#000'],
    },
  },

  childrenThemes: {
    blue: {
      palette: {
        light: Object.values(Colors.blue),
        dark: Object.values(Colors.blueDark),
      },
    },
    red: {
      palette: { light: Object.values(Colors.red), dark: Object.values(Colors.redDark) },
    },
  },

  grandChildrenThemes: {
    accent: { template: 'inverse' },
  },
})
```

--------------------------------

### Install Tamagui Full UI Kit

Source: https://tamagui.dev/docs/intro/installation.md

Install the complete Tamagui package, which includes the core library and the full UI kit. This is a superset of @tamagui/core.

```bash
yarn add tamagui
```

--------------------------------

### Detailed Tamagui Configuration Example

Source: https://tamagui.dev/docs/core/configuration.md

A more detailed example of a Tamagui configuration file. It illustrates setting up tokens for size, space, radius, and color, defining themes, media queries, shorthands, and other settings.

```typescript
import { createTamagui, getConfig } from 'tamagui'

export const config = createTamagui({
  // tokens work like CSS Variables (and compile to them on the web)
  // accessible from anywhere, never changing dynamically:
  tokens: {
    // width="$sm"
    size: { sm: 8, md: 12, lg: 20 },
    // margin="$sm"
    space: { sm: 4, md: 8, lg: 12 },
    // radius="$none"
    radius: { none: 0, sm: 3 },
    color: { white: '#fff', black: '#000' },
  },

  // themes are like CSS Variables that you can change anywhere in the tree
  // you use <Theme name="light" /> to change the theme
  themes: {
    light: {
      bg: '#f2f2f2',
      color: '#000',
    },
    dark: {
      bg: '#111',
      color: '#fff',
    },
    // sub-themes are a powerful feature of tamagui, explained later in the docs
    // user theme like <Theme name="dark"><Theme name="blue">
    // or just <Theme name="dark_blue">
    dark_blue: {
      bg: 'darkblue',
      color: '#fff',
    },
  },

  // media query definitions can be used as style props or with the useMedia hook
  // but also are added to "group styles", which work like Container Queries from CSS
  media: {
    sm: { maxWidth: 860 },
    gtSm: { minWidth: 860 + 1 },
    short: { maxHeight: 820 },
    hoverable: { hover: 'hover' },
    touchable: { pointer: 'coarse' },
  },

  shorthands: {
    // <View px={20} />
    px: 'paddingHorizontal',
  },

  // there are more settings, explained below:
  settings: {
    disableSSR: true,
    allowedStyleValues: 'somewhat-strict-web',
  },
})

// now, make your types flow nicely back to your `tamagui` import:
type OurConfig = typeof config

declare module 'tamagui' {
  interface TamaguiCustomConfig extends OurConfig {}
}
```

--------------------------------

### Install Motion Driver

Source: https://tamagui.dev/docs/core/animations-motion.md

Install the Motion driver and its dependencies using yarn.

```bash
yarn add @tamagui/animations-motion motion
```

--------------------------------

### Basic Button Example

Source: https://tamagui.dev/docs/intro/installation.md

A simple example demonstrating how to use the Button component from Tamagui with a theme applied.

```tsx
import { Button } from 'tamagui'

export default function Demo() {
  return <Button theme="blue">Hello world</Button>
}
```

--------------------------------

### Install Button component

Source: https://tamagui.dev/docs/components/button

Commands to install the @tamagui/button package using various package managers.

```bash
yarn
npm
bun
pnpm
yarn add @tamagui/button
```

--------------------------------

### Tamagui Build Configuration Example

Source: https://tamagui.dev/docs/guides/cli.md

Example of a `tamagui.build.ts` configuration file. This file is essential for the Tamagui build process and should correctly point to your main Tamagui configuration file and specify components to include.

```typescript
export default {
  config: './tamagui.config.ts', // Verify this path is correct
  components: ['tamagui'],
}
```

--------------------------------

### Install React Native Animations Driver

Source: https://tamagui.dev/docs/core/animations-react-native.md

Install the necessary package using yarn.

```bash
yarn add @tamagui/animations-react-native
```

--------------------------------

### Install Tamagui CLI

Source: https://tamagui.dev/docs/guides/cli.md

Install the Tamagui CLI as a development dependency using yarn.

```bash
yarn add -D @tamagui/cli
```

--------------------------------

### Install Tamagui Configuration Preset

Source: https://tamagui.dev/docs/intro/installation.md

Add the recommended preset configuration package for Tamagui. This simplifies setting up your Tamagui environment.

```bash
yarn add @tamagui/config
```

--------------------------------

### Advanced Stack Configuration

Source: https://tamagui.dev/docs/components/stacks

Example demonstrating various style properties including hover states and media queries.

```tsx
import { Text, XStack, YStack } from 'tamagui'



export default () => (

  <XStack
    flex={1}
    flexWrap="wrap"
    backgroundColor="#fff"
    hoverStyle={{
      backgroundColor: 'red',
    }}
    // media query
    $gtSm={{
      flexDirection: 'column',
      flexWrap: 'nowrap',
    }}
  >

    <YStack gap="$3">

      <Text>Hello</Text>

      <Text>World</Text>

    </YStack>

  </XStack>

)
```

--------------------------------

### Basic Tamagui Configuration

Source: https://tamagui.dev/docs/core/configuration.md

Set up a basic Tamagui configuration file. This example demonstrates how to extend the default configuration with custom media queries and declare your configuration types.

```typescript
import { defaultConfig } from '@tamagui/config/v5'
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  media: {
    ...defaultConfig.media,
    // add your own media queries here, if wanted
  },
})

type OurConfig = typeof config

declare module 'tamagui' {
  interface TamaguiCustomConfig extends OurConfig {}
}
```

--------------------------------

### Example package.json Scripts for Expo

Source: https://tamagui.dev/docs/guides/expo.md

Example scripts in package.json for running an Expo project with Tamagui, including cache clearing and platform-specific builds.

```json
{
  "scripts": {
    "start-native": "expo start -c",
    "start-web": "expo start -c",
    "android": "yarn expo run:android",
    "ios": "yarn expo run:ios",
    "web": "expo start --web"
  }
}
```

--------------------------------

### Minimal Manual Webpack Setup

Source: https://tamagui.dev/docs/guides/webpack.md

A minimal setup for Webpack, including DefinePlugin for environment variables, aliasing react-native to react-native-web, and setting up web extensions.

```javascript
// some stuff for react-native
config.plugins.push(
  new webpack.DefinePlugin({
    process: {
      env: {
        __DEV__: process.env.NODE_ENV === 'development' ? 'true' : 'false',
        NODE_ENV: JSON.stringify(process.env.NODE_ENV),
      },
    },
  })
)

config.resolve.alias['react-native$'] = 'react-native-web'

// set up web extensions
compiler.options.resolve.extensions = [
  '.web.tsx',
  '.web.ts',
  '.web.js',
  '.ts',
  '.tsx',
  '.js',
]
```

--------------------------------

### Install Metro Plugin

Source: https://tamagui.dev/docs/guides/metro.md

Install the `@tamagui/metro-plugin` package to enhance the development experience by loading your Tamagui config and watching for changes.

```bash
yarn add @tamagui/metro-plugin
```

--------------------------------

### Install Vite Project

Source: https://tamagui.dev/docs/guides/vite.md

Use this command to create a new Vite project. Ensure your project is ESM-only.

```bash
npm create vite@latest
```

--------------------------------

### Install Stacks package

Source: https://tamagui.dev/docs/components/stacks

Commands to install the @tamagui/stacks package using various package managers.

```bash
yarn
npm
bun
pnpm
yarn add @tamagui/stacks
```

--------------------------------

### Install Tamagui Loader

Source: https://tamagui.dev/docs/guides/webpack.md

Install the tamagui-loader package, which is required for Webpack integration.

```bash
yarn add -D tamagui-loader
```

--------------------------------

### Install React Native for Web-Only Apps

Source: https://tamagui.dev/docs/intro/compiler-install.md

For web-only apps, install `react-native` to enable prop typing and autocomplete. This is required for Tamagui's web runtime.

```bash
yarn add react-native
```

--------------------------------

### TamaguiProvider with Preset Configuration

Source: https://tamagui.dev/docs/intro/installation.md

Set up TamaguiProvider using the preset configuration. This example demonstrates creating a typed configuration and exporting it.

```tsx
import { TamaguiProvider, createTamagui } from '@tamagui/core'
import { defaultConfig } from '@tamagui/config/v5'

// you usually export this from a tamagui.config.ts file
const config = createTamagui(defaultConfig)

type Conf = typeof config

// make imports typed
declare module '@tamagui/core' {
  interface TamaguiCustomConfig extends Conf {}
}

export default () => {
  return <TamaguiProvider config={config} defaultTheme="light">{/* your app here */}</TamaguiProvider>
}
```

--------------------------------

### Tamagui Build Output Example

Source: https://tamagui.dev/docs/guides/design-systems.md

Example of Tamagui's build output indicating successful component compilation and optimization. This output appears when `logTimings: true` is set.

```bash
tamagui built app.tsx in 16ms (1 optimized, 1 flattened)
```

--------------------------------

### Basic TamaguiProvider Setup

Source: https://tamagui.dev/docs/intro/installation.md

Integrate Tamagui into your application by wrapping your root component with TamaguiProvider. Ensure you import your Tamagui configuration.

```tsx
import { TamaguiProvider, View } from '@tamagui/core'
import config from './tamagui.config' // your configuration

export default function App() {
  return (
    <TamaguiProvider config={config} defaultTheme="light">
      <View width={200} height={200} backgroundColor="$background" />
    </TamaguiProvider>
  )
}
```

--------------------------------

### Compiler Debug Output Example

Source: https://tamagui.dev/docs/guides/metro.md

Example of the compiler debug output when `// debug` is enabled, showing flattened component structures.

```text
[✅] flattened YStack div
```

--------------------------------

### Metro Configuration with Tamagui Plugin (Recommended)

Source: https://tamagui.dev/docs/guides/metro.md

Configure Metro to use the `@tamagui/metro-plugin`. This setup automatically reads your `tamagui.build.ts` configuration for optimal development.

```javascript
const { getDefaultConfig } = require('expo/metro-config')
const { withTamagui } = require('@tamagui/metro-plugin')

const config = getDefaultConfig(__dirname)

// reads from tamagui.build.ts automatically
module.exports = withTamagui(config)
```

--------------------------------

### Setup Tamagui Visualizer

Source: https://tamagui.dev/docs/guides/developing.md

Configure the visualizer to display component names and file information as an overlay in development mode. Set the key to trigger the visualizer and the delay before it appears.

```tsx
import { setupDev } from '@tamagui/core'

setupDev({
  // can just be true as well for defaulting to key: Alt + delay: 800
  visualizer: {
    key: 'Alt',
    delay: 800,
  },
})
```

--------------------------------

### Migrate Theme Creation

Source: https://tamagui.dev/docs/guides/how-to-upgrade.md

Use createV5Theme for a simplified theme setup compared to the manual theme-builder approach.

```tsx
// before (v1) - manual theme-builder
import { createThemes, defaultComponentThemes } from '@tamagui/theme-builder'
const themes = createThemes({ ... })

// after (v2) - simplified
import { createV5Theme, defaultChildrenThemes } from '@tamagui/themes/v5'
const themes = createV5Theme({
  childrenThemes: {
    ...defaultChildrenThemes,
    // add custom color themes
    cyan: { light: cyan, dark: cyanDark },
  },
})
```

--------------------------------

### Basic Stack Usage

Source: https://tamagui.dev/docs/components/stacks

Example of using XStack and YStack components with the gap property.

```tsx
import { XStack, YStack } from 'tamagui'



export default () => (

  <XStack gap="$2">

    <YStack />

    <YStack />

    <YStack />

  </XStack>

)
```

--------------------------------

### Install React Native Types for Web-Only Apps

Source: https://tamagui.dev/docs/intro/compiler-install.md

Alternatively, if you only need the types for `react-native` in web-only apps, install `@types/react-native` alongside `react-native@0.0.0`.

```bash
yarn add react-native@0.0.0 @types/react-native
```

--------------------------------

### Add Tamagui Vite Plugin

Source: https://tamagui.dev/docs/guides/vite.md

Install the Tamagui Vite plugin to enable Tamagui support. Your project must be ESM-only.

```bash
yarn add @tamagui/vite-plugin
```

--------------------------------

### Configure Native Features

Source: https://tamagui.dev/docs/guides/how-to-upgrade.md

Import these setup modules at the top of your app entry point before any Tamagui imports to enable native features.

```tsx
// portals (Sheet, Dialog, Popover, Select, Toast)
import '@tamagui/native/setup-teleport'

// LinearGradient
import '@tamagui/native/setup-expo-linear-gradient'

// Toast (burnt)
import '@tamagui/native/setup-burnt'

// Menu (zeego)
import '@tamagui/native/setup-zeego'

// for smoother Sheet on native:
import '@tamagui/native/setup-gesture-handler'
```

--------------------------------

### Configure Expo Router Entry Point

Source: https://tamagui.dev/docs/guides/how-to-upgrade.md

Create a custom entry point to ensure native setup imports run before Expo Router initializes.

```js
// index.js (at project root)
import '@tamagui/native/setup-zeego'
// add other setup imports here as needed

import 'expo-router/entry'
```

```json
{
  "main": "index.js"
}
```

--------------------------------

### Setup Tamagui Provider in Root Layout

Source: https://tamagui.dev/docs/guides/one.md

Wrap your application with TamaguiProvider and use Slot for routing in your root layout file.

```tsx
import { TamaguiProvider } from 'tamagui'
import { Slot } from 'one'
import config from '../tamagui.config'

export default function Layout() {
  return (
    <TamaguiProvider config={config}>
      <Slot />
    </TamaguiProvider>
  )
}
```

--------------------------------

### Add Tamagui Dependencies

Source: https://tamagui.dev/docs/guides/one.md

Install Tamagui and its configuration package using yarn.

```bash
yarn add tamagui @tamagui/config
```

--------------------------------

### Tamagui Configuration File

Source: https://tamagui.dev/docs/guides/expo.md

Create a tamagui.config.ts file to define your Tamagui configuration. This example uses the default v5 configuration.

```typescript
import { defaultConfig } from '@tamagui/config/v5'
import { createTamagui } from 'tamagui'

export const tamaguiConfig = createTamagui(defaultConfig)

export default tamaguiConfig

export type Conf = typeof tamaguiConfig

declare module 'tamagui' {
  interface TamaguiCustomConfig extends Conf {}
}
```

--------------------------------

### TamaguiProvider Setup

Source: https://tamagui.dev/docs/core/configuration.md

Integrate your custom Tamagui configuration by passing it to the TamaguiProvider at the root of your application. This makes your configuration available throughout your app.

```typescript
import { TamaguiProvider, View } from 'tamagui'
import { config } from './tamagui.config.ts'

export default () => (
  <TamaguiProvider config={config}>
    <View margin="$sm" />
  </TamaguiProvider>
)
```

--------------------------------

### Add Tamagui Babel Plugin

Source: https://tamagui.dev/docs/guides/expo.md

Install the Tamagui Babel plugin to enable the optimizing compiler. This is a required step for Tamagui integration.

```bash
yarn add @tamagui/babel-plugin
```

--------------------------------

### ClientOnly Component Example for Deferring UI

Source: https://tamagui.dev/docs/core/server-rendering.md

Demonstrates using `ClientOnly` to defer rendering complex or non-critical UI until after the initial server render, improving perceived performance.

```tsx
function ProductPage({ product }) {
  return (
    <YStack>
      {/* SEO-critical content */}
      <ProductHeader product={product} />

      {/* Defer complex UI */}
      <ClientOnly enabled>
        <InteractiveGallery />
      </ClientOnly>
    </YStack>
  )
}
```

--------------------------------

### Example Usage of CSS Animations

Source: https://tamagui.dev/docs/core/animations-css.md

Demonstrates how to configure and use CSS animations in Tamagui components, including hover effects.

```tsx
import { createAnimations } from '@tamagui/animations-css'
import { YStack, createTamagui } from 'tamagui'

const animations = createAnimations({
  quick: 'ease-out 150ms',
  bouncy: 'cubic-bezier(0.68, -0.55, 0.265, 1.55) 400ms',
})

export default createTamagui({
  animations,
  // ... rest of config
})

// Usage in components
export const MyComponent = () => (
  <YStack
    transition="quick"
    hoverStyle={{
      scale: 1.1,
    }}
  />
)
```

--------------------------------

### Add Native Dependencies

Source: https://tamagui.dev/docs/guides/create-tamagui-app.md

Steps for installing libraries with native code into the `apps/expo` directory. It's crucial to maintain version consistency if the same library is used in `packages/app`.

```bash
cd apps/expo
yarn add react-native-reanimated

cd ../..
yarn
```

--------------------------------

### Create a New One Project

Source: https://tamagui.dev/docs/guides/one.md

Use this command to initialize a new One.js project.

```bash
npx one
```

--------------------------------

### Tamagui CLI Usage Examples

Source: https://tamagui.dev/docs/intro/compiler-install.md

Demonstrates various ways to use the Tamagui CLI for building components. Options include targeting specific platforms, including/excluding files, specifying output directories, and performing dry runs.

```bash
# Build all components in a directory (web + native by default)
npx tamagui build ./src
```

```bash
# Build for web only
npx tamagui build --target web ./src
```

```bash
# Build for native only
npx tamagui build --target native ./src
```

```bash
# Build a specific file
npx tamagui build ./src/components/MyComponent.tsx
```

```bash
# Include/exclude patterns
npx tamagui build --include "components/**" --exclude "**/*.test.tsx" ./src
```

```bash
# Output to a separate directory (source files unchanged)
npx tamagui build --output ./dist ./src
```

```bash
# Create platform-specific files next to source files (.web.tsx or .native.tsx)
npx tamagui build --target native --output-around ./src
```

```bash
# Preview changes without writing files
npx tamagui build --dry-run ./src
```

```bash
# Verify minimum optimizations (useful in CI)
npx tamagui build --target web --expect-optimizations 10 ./src
```

--------------------------------

### Bundler Plugin Integration

Source: https://tamagui.dev/docs/intro/compiler-install.md

Example comments showing how Tamagui compiler plugins integrate with different bundlers. These plugins automatically read configuration from `tamagui.build.ts`.

```tsx
// vite: tamaguiPlugin()
// webpack: new TamaguiPlugin()
// metro: withTamagui(config)
// all read from tamagui.build.ts automatically
```

--------------------------------

### Basic Metro Configuration

Source: https://tamagui.dev/docs/guides/metro.md

Use the default Expo Metro configuration for basic Tamagui setup. No additional configuration is needed for this to work out of the box.

```javascript
const { getDefaultConfig } = require('expo/metro-config')

module.exports = getDefaultConfig(__dirname)
```

--------------------------------

### Create a New Next.js Project

Source: https://tamagui.dev/docs/guides/next-js.md

Use this command to initialize a new Next.js application.

```bash
npx create-next-app@latest
```

--------------------------------

### Install expo-font Package

Source: https://tamagui.dev/docs/guides/expo.md

Install the necessary expo-font package to manage fonts in your Expo project.

```bash
npx expo install expo-font
```

--------------------------------

### Create Default V5 Themes

Source: https://tamagui.dev/docs/guides/theme-builder.md

Use `createV5Theme` with no arguments to generate a production-ready suite of light, dark, accent, and color themes with sensible defaults. This is the simplest way to get a complete theme suite.

```typescript
import { createV5Theme } from '@tamagui/themes/v5'

// zero-config - includes light, dark, accent, and color themes
export const themes = createV5Theme()
```

--------------------------------

### Install Reanimated Driver

Source: https://tamagui.dev/docs/core/animations-reanimated.md

Install the Reanimated driver and React Native Reanimated library using yarn.

```bash
yarn add @tamagui/animations-reanimated react-native-reanimated
```

--------------------------------

### Create Tamagui App

Source: https://tamagui.dev/docs/guides/create-tamagui-app.md

Use this command to initialize a new Tamagui project with the latest starter template.

```bash
npm create tamagui@latest
```

--------------------------------

### Reanimated Driver Example

Source: https://tamagui.dev/docs/core/animations-reanimated.md

Example of configuring Reanimated animations and using them with a component's transition and enterStyle.

```tsx
import { createAnimations } from '@tamagui/animations-reanimated'
import { YStack, createTamagui } from 'tamagui'

const animations = createAnimations({
  bouncy: {
    type: 'spring',
    damping: 10,
    mass: 0.9,
    stiffness: 100,
  },
  quick: {
    type: 'spring',
    damping: 20,
    mass: 1.2,
    stiffness: 250,
  },
})

export default createTamagui({
  animations,
  // ... rest of config
})

// Usage in components
export const MyComponent = () => (
  <YStack
    transition="bouncy"
    enterStyle={{
      opacity: 0,
      scale: 0.9,
    }}
  />
)
```

--------------------------------

### Create Theme Builder Instance

Source: https://tamagui.dev/docs/guides/theme-builder.md

Initialize the theme builder and configure palettes, templates, and themes.

```tsx
import { createThemeBuilder } from '@tamagui/theme-builder'

const themesBuilder = createThemeBuilder()
  .addPalettes({
    dark: ['#000', '#111', '#222', '#999', '#ccc', '#eee', '#fff'],
    light: ['#fff', '#eee', '#ccc', '#999', '#222', '#111', '#000'],
  })
  .addTemplates({
    base: { background: 0, color: -0 },
    subtle: { background: 1, color: -1 },
  })
  .addThemes({
    light: { template: 'base', palette: 'light' },
    dark: { template: 'base', palette: 'dark' },
  })
  .addChildThemes({
    subtle: { template: 'subtle' },
  })

export const themes = themesBuilder.build()
```

--------------------------------

### Install Expo Google Fonts Inter Package

Source: https://tamagui.dev/docs/guides/expo.md

Install a specific Google Font package, such as @expo-google-fonts/inter, for use with Expo.

```bash
npx expo install @expo-google-fonts/inter
```

--------------------------------

### Start Expo Project with Cache Clear

Source: https://tamagui.dev/docs/guides/expo.md

When first starting your Expo project with Tamagui, clear the cache to ensure a clean build.

```bash
npx expo start -c
```

--------------------------------

### Basic styled() component creation

Source: https://tamagui.dev/docs/core/styled.md

Demonstrates the initial creation of a styled component using the styled() utility.

```tsx
const StyledText = styled(Text)
```

--------------------------------

### Minimal Vite Setup for React Native Web

Source: https://tamagui.dev/docs/guides/vite.md

A minimal Vite setup for compatibility with react-native-web and React Native extensions. This configures aliases and esbuild options.

```typescript
config.define = {
  __DEV__: `${process.env.NODE_ENV === 'development' ? true : false}`,
  'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV),
}

config.resolve.alias['react-native'] = 'react-native-web'

// set up web extensions
config.optimizeDeps.esbuildOptions = {
  ...config.optimizeDeps.esbuildOptions,
  resolveExtensions: [
    '.web.js',
    '.web.jsx',
    '.web.ts',
    '.web.tsx',
    '.mjs',
    '.js',
    '.mts',
    '.ts',
    '.jsx',
    '.tsx',
    '.json',
  ],
  loader: {
    '.js': 'jsx',
  },
}
```

--------------------------------

### Setting up createStyledContext for Compound Components

Source: https://tamagui.dev/docs/core/create-styled-context.md

This snippet shows the setup for createStyledContext, defining a context with shared properties like 'size' and then creating styled components (ButtonFrame, ButtonText) that utilize this context and its variants.

```tsx
import {
  SizeTokens,
  View,
  Text,
  createStyledContext,
  styled,
  withStaticProperties,
} from '@tamagui/core'

export const ButtonContext = createStyledContext<{
  size: SizeTokens
}>({
  size: '$medium',
})

export const ButtonFrame = styled(View, {
  name: 'Button',
  context: ButtonContext,

  variants: {
    size: {
      '...size': (name, { tokens }) => {
        return {
          height: tokens.size[name],
          borderRadius: tokens.radius[name],
          gap: tokens.space[name].val * 0.2,
        }
      },
    },
  } as const,

  defaultVariants: {
    size: '$medium',
  },
})

export const ButtonText = styled(Text, {
  name: 'ButtonText',
  context: ButtonContext,

  variants: {
    size: {
      '...fontSize': (name, { font }) => ({
        fontSize: font?.size[name],
      }),
    },
  } as const,
})

export const Button = withStaticProperties(ButtonFrame, {
  Props: ButtonContext.Provider,
  Text: ButtonText,
})
```

--------------------------------

### Install Tamagui Loader for Webpack

Source: https://tamagui.dev/docs/intro/compiler-install.md

Add the tamagui-loader package to your project dependencies.

```bash
yarn add tamagui-loader
```

--------------------------------

### Tamagui Build with Output Directory

Source: https://tamagui.dev/docs/guides/cli.md

Use the `--output` flag to write optimized files to a separate directory, leaving source files unmodified. This approach requires no restoration.

```json
{
  "scripts": {
    "build": "tamagui build --target web --output ./dist ./src && next build"
  }
}
```

--------------------------------

### Define a Color Palette

Source: https://tamagui.dev/docs/guides/theme-builder.md

Example of defining a dark blue color palette using HSL values.

```javascript
const dark_blue = [
  'hsl(212, 35.0%, 9.2%)', // background
  'hsl(216, 50.0%, 11.8%)',
  // ...
  'hsl(206, 98.0%, 95.8%)', // foreground
]
```

--------------------------------

### Generate Tamagui Configuration and CSS

Source: https://tamagui.dev/docs/guides/cli.md

Use this command to build your entire Tamagui configuration and output CSS. It's useful for pre-generating your design system's CSS and validating your configuration. It loads, validates, and generates CSS for tokens, themes, and components, outputting to the `.tamagui` directory and creating a prompt file.

```bash
npx tamagui generate
```

--------------------------------

### Build-time Theme Generation (CLI)

Source: https://tamagui.dev/docs/guides/theme-builder.md

Use the Tamagui CLI to generate themes from an input file to an output file.

```bash
npx @tamagui/cli generate-themes ./src/themes-in.ts ./src/themes-out.ts
```

--------------------------------

### Web Animation Configuration

Source: https://tamagui.dev/docs/core/animations-motion.md

Define web-specific animations using the Motion driver. This example shows a 'bouncy' spring animation.

```ts
// animations.ts (web)
import { createAnimations } from '@tamagui/animations-motion'

export const animations = createAnimations({
  bouncy: {
    type: 'spring',
    damping: 10,
    stiffness: 100,
  },
})
```

--------------------------------

### Configure Tamagui Next Plugin in next.config.js

Source: https://tamagui.dev/docs/guides/next-js.md

Integrate the Tamagui plugin into your `next.config.js` file. This setup is for projects not using Turbopack.

```tsx
const {
  withTamagui
} = require('@tamagui/next-plugin')

module.exports = function (name, { defaultConfig }) {
  let config = {
    ...defaultConfig,
    // ...your configuration
  }
  const tamaguiPlugin = withTamagui({
    config: './tamagui.config.ts',
    components: ['tamagui'],
  })
  return {
    ...config,
    ...tamaguiPlugin(config),
  }
}
```

--------------------------------

### Configure Themes with Tokens

Source: https://tamagui.dev/docs/core/configuration.md

Define themes within `createTamagui` by referencing color tokens. Themes act as fallbacks to tokens, allowing for consistent styling across different states like hover and press.

```tsx
const config = createTamagui({
  themes: {
    light: {
      background: '#fff',
      backgroundHover: tokens.color.gray2,
      // ...
      color: tokens.color.gray10,
      colorHover: tokens.color.gray9,
      colorPress: tokens.color.gray8,
      // ...
      color1: tokens.color.gray1,
    },
    dark: {
      background: '#000',
      // ... matching the properties for light ^
    },
  },
  // ... the rest of your configuration
})
```

--------------------------------

### Initialize TamaguiProvider in App

Source: https://tamagui.dev/docs/core/configuration.md

Import and use TamaguiProvider at the root of your application, passing your configuration and default theme.

```tsx
import { TamaguiProvider } from 'tamagui'
import { config } from './tamagui.config'

export default function App() {
  return (
    <TamaguiProvider config={config} defaultTheme="light">
      <AppContents />
    </TamaguiProvider>
  )
}
```

--------------------------------

### Configure Next.js with @tamagui/next-plugin

Source: https://tamagui.dev/docs/intro/compiler-install.md

Integrate @tamagui/next-plugin into your next.config.js for Webpack-based Next.js projects. This setup automates configuration, especially when using tamagui.build.ts.

```javascript
const { withTamagui } = require('@tamagui/next-plugin')

module.exports = function (name, { defaultConfig }) {
  const tamaguiPlugin = withTamagui({
    // reads from tamagui.build.ts automatically, or pass inline:
    config: './tamagui.config.ts',
    components: ['tamagui'],
    disableExtraction: process.env.NODE_ENV === 'development',
    excludeReactNativeWebExports: ['Switch', 'ProgressBar', 'Picker'],
  })
  return {
    ...defaultConfig,
    ...tamaguiPlugin(defaultConfig),
  }
}
```

--------------------------------

### Configure Webpack with tamagui-loader

Source: https://tamagui.dev/docs/intro/compiler-install.md

Manually configure your webpack.config.js to include tamagui-loader and its options. This setup includes resolving react-native-web and optionally react-native-svg.

```javascript
const { shouldExclude } = require('tamagui-loader')

const tamaguiOptions = {
  config: './tamagui.config.ts',
  components: ['tamagui'],
  importsWhitelist: ['constants.js', 'colors.js'],
  logTimings: true,
  disableExtraction: process.env.NODE_ENV === 'development',
  // optional advanced optimization of styled() definitions within your app itself, not just ones in your components option
  // default is false
  enableDynamicEvaluation: false,
}

module.exports = {
  resolve: {
    alias: {
      // Resolve react-native to react-native-web
      'react-native$': require.resolve('react-native-web'),
      // optional, for lighter svg icons on web
      'react-native-svg': require.resolve('@tamagui/react-native-svg'),
    },
  },
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        // you'll likely want to adjust this helper function,
        // but it serves as a decent start that you can copy/paste from
        exclude: (path) => shouldExclude(path, __dirname, tamaguiOptions),
        use: [
          // optionally thread-loader for significantly faster compile!
          'thread-loader',

          // works nicely alongside esbuild
          {
            loader: 'esbuild-loader',
          },

          {
            loader: 'tamagui-loader',
            options: tamaguiOptions,
          },
        ],
      },
    ],
  },
}
```

--------------------------------

### Use Tamagui Components in One App

Source: https://tamagui.dev/docs/guides/one.md

Example of using Tamagui components like YStack, Text, and Button within a One application.

```tsx
import { Button, Text, YStack } from 'tamagui'

export default function Home() {
  return (
    <YStack f={1} jc="center" ai="center" p="$4" gap="$4">
      <Text fontSize="$6">Welcome to Tamagui with One!</Text>
      <Button>Click me</Button>
    </YStack>
  )
}
```

--------------------------------

### Enter Animations

Source: https://tamagui.dev/docs/core/animations.md

Define initial styles for components that animate to their base styles after mounting using the `enterStyle` prop.

```tsx
import { Square, Paragraph, YStack } from 'tamagui'

export default () => (
  <YStack>
    <Paragraph>Animate in</Paragraph>
    <Square
      enterStyle={{
        opacity: 0,
        scale: 0.5,
        y: 20,
      }}
      animation={{
        type: 'spring',
        damping: 10,
        stiffness: 100,
      }}
      size={60}
      bg="$color5"
    />
  </YStack>
)
```

--------------------------------

### Metro Configuration with Inline Options

Source: https://tamagui.dev/docs/guides/metro.md

Configure Metro with the Tamagui plugin by passing options directly. Specify the components and configuration file to be used.

```javascript
const { getDefaultConfig } = require('expo/metro-config')
const { withTamagui } = require('@tamagui/metro-plugin')

const config = getDefaultConfig(__dirname)

module.exports = withTamagui(config, {
  components: ['tamagui'],
  config: './tamagui.config.ts',
})
```

--------------------------------

### Example Usage of React Native Animations

Source: https://tamagui.dev/docs/core/animations-react-native.md

Integrate the configured animations into your components using the transition prop and enterStyle for initial animation states.

```tsx
import { createAnimations } from '@tamagui/animations-react-native'
import { YStack, createTamagui } from 'tamagui'

const animations = createAnimations({
  bouncy: {
    damping: 10,
    mass: 0.9,
    stiffness: 100,
  },
  quick: {
    damping: 20,
    mass: 1.2,
    stiffness: 250,
  },
})

export default createTamagui({
  animations,
  // ... rest of config
})

// Usage in components
export const MyComponent = () => (
  <YStack
    transition="bouncy"
    enterStyle={
      {
        opacity: 0,
        scale: 0.9,
      }
    }
  />
)
```

--------------------------------

### Configure Animations with Config v5

Source: https://tamagui.dev/docs/core/animation-drivers.md

Use the v5 config presets for pre-configured animations across all drivers. Import the default config and animations from '@tamagui/config/v5'.

```tsx
import { defaultConfig } from '@tamagui/config/v5'
import { animations } from '@tamagui/config/v5-css' // or v5-motion, v5-rn, v5-reanimated
import { createTamagui } from 'tamagui'

export const config = createTamagui({
  ...defaultConfig,
  animations,
})
```

--------------------------------

### Get HTMLElement from TamaguiElement

Source: https://tamagui.dev/docs/core/exports.md

Use `getWebElement` to narrow a TamaguiElement to an HTMLElement. It throws if the element is not an HTMLElement. You can also specify the expected HTMLElement type.

```tsx
import { getWebElement } from 'tamagui' // or '@tamagui/element'

// Narrows to HTMLElement
const el = getWebElement(ref.current)

// Or narrow to a specific element type
const input = getWebElement<HTMLInputElement>(ref.current)
input.selectionStart // typed correctly
```
Tokens:
Raw