Tamagui

2.0.0-rc.41 verified Fri May 01 auth: no javascript

Tamagui v2.0.0-rc.41 is a UI library and optimizing compiler for React (web and native). It provides a design system with styled components, theming, and responsive props, aiming to reduce bundle size and runtime overhead through compile-time optimizations. Released as release candidates since 2023, it requires React 19 and offers deep integration with React Native. Key differentiators include its compiler that transforms styled components into optimized CSS or native code, and its cross-platform support without platform-specific code forks.

Common errors

error Module not found: Can't resolve 'tamagui' ↓

cause Package not installed or incorrectly referenced

fix

Run 'npm install tamagui@latest' and ensure the import path is correct (case-sensitive).

error Uncaught Error: Tamagui must be initialized with a valid config ↓

cause Missing or invalid Tamagui configuration

fix

Create a Tamaqui config using createTamagui() and wrap your app with it.

error TypeError: Cannot read properties of undefined (reading 'styled') ↓

cause Named import 'styled' is undefined, possibly due to CJS vs ESM mismatch

fix

Ensure you are using ES module import syntax and have set 'type': 'module' in package.json if applicable.

error Warning: React version mismatch. Expected React 19, found React 18 ↓

cause Using React version below 19

fix

Upgrade React to version 19.

Warnings

gotcha Tamagui v2 requires React 19. Using older React versions will cause runtime errors. ↓

fix Upgrade React to version 19 or later.

gotcha The package is ESM-only; using require() or CJS may fail, especially in Node.js environments. ↓

fix Use ES module imports (import) in your project or configure bundler to handle ESM.

deprecated The old 'animations' package has been replaced; imports from '@tamagui/animations' may not work. ↓

fix Use the new 'animationsReanimated' or 'animationsCSS' imports from tamagui.

breaking Web-only builds now require TAMAGUI_TARGET guard to strip react-native code; missing this guard may cause errors. ↓

fix Set TAMAGUI_TARGET='web' in your build environment.

gotcha Default export from 'tamagui' is not available; only named exports exist. ↓

fix Use named imports like import { styled } from 'tamagui'.

Install

npm install tamagui

yarn add tamagui

pnpm add tamagui

Imports

styled
wrong
```
const { styled } = require('tamagui')
```
correct
```
import { styled } from 'tamagui'
```
ESM-only package; CommonJS require may fail in newer versions

Theme

wrong

import { Theme } from '@tamagui/core'

correct

import { Theme } from 'tamagui'

Main export is from 'tamagui', not '@tamagui/core'

YStack
wrong
```
import { YStack } from '@tamagui/stacks'
```
correct
```
import { YStack } from 'tamagui'
```
YStack is re-exported from tamagui; direct subpath imports may change

Quickstart

Basic usage of Tamagui with styled components, theming, and responsive spacing tokens.

import { createTamagui, styled, Theme, YStack, Text, Button } from 'tamagui'
import { config } from './tamagui.config' // assume config exported

const App = () => (
  <Theme name='light'>
    <YStack padding='$4' space='$2'>
      <Text fontSize='$6' fontWeight='bold'>Hello Tamagui</Text>
      <Button onPress={() => alert('Clicked!')}>Click me</Button>
    </YStack>
  </Theme>
)

export default App