Installation — Tamagui

Installation

How to get Tamagui set up.

Tamagui is a full-featured UI kit built on top of @tamagui/core. The instructions here are for using tamagui: a more complete set of components designed to build entire apps out of the box. It's tree-shakeable so only adds to your bundle what you use. If you'd rather build your own design system on top of core, see the Design Systems guide. Install Tamagui

yarn add tamagui react-native-web

# for web, webpack, only:
yarn add tamagui-loader

# for react-native, only:
yarn add @tamagui/babel-plugin

Set up your build

For more information on the options, see the compiler options. Whether using Webpack or Next.js, be sure to not use the Tamagui babel plugin in your web build! They are either-or: the babel plugin only for React Native, and tamagui-loader or next plugin only for web. Webpack Add tamagui-loader and set up your webpack.config.js:

{
  module: {
    rules: [
      {
        test: /\.[jt]sx?$/,
        // be sure to include tamagui
        include: /tamagui/,
        use: [
          // optionally thread-loader for significantly faster compile!
          'thread-loader',

          // works nicely alongside esbuild
          'esbuild-loader',

          {
            loader: 'tamagui-loader',
            options: {
              config: './tamagui.config.ts',
              components: ['tamagui'],
              importsWhitelist: ['constants.js', 'colors.js'],
              logTimings: true,
              disableExtraction: process.env.NODE_ENV === 'development',
            },
          },
        ]
      }
    ]
  },
  plugins: [
    new webpack.DefinePlugin({
      'process.env.TAMAGUI_TARGET': '"web"',
    })
  ]
}

Next.js

Support only for Next.js 11 right now

Add @tamagui/next-plugin and configure your next.config.js:

const withPlugins = require('next-compose-plugins')
const { withTamagui } = require('@tamagui/next-plugin')

export default withPlugins([
  withTamagui({
    config: './tamagui.config.ts',
    components: ['tamagui'],
    importsWhitelist: ['constants.js', 'colors.js'],
    logTimings: true,
    disableExtraction: process.env.NODE_ENV === 'development',
  })
])

React Native Add @tamagui/babel-plugin to your babel.config.js plugins:

module.exports = {
  plugins: [
    [
      '@tamagui/babel-plugin',
      {
        components: ['tamagui'],
        config: './tests/lib/tamagui.config.js',
        importsWhitelist: ['constants.js', 'colors.js'],
        logTimings: true,
        disableExtraction: process.env.NODE_ENV === 'development',
      }
    ]
  ]
}

We've noticed errors in other versions (0.65.5), so you may want to pin @types/react-native to 0.66.6. Compiler options

The webpack loader and Next.js plugin accept the same configuration options:

Prop	Type	Default
`config*`	`string`
Relative path to your tamagui.config.ts file which should export default the result from createTamagui.
`components`	`string[]`	`['tamagui']`
Array of npm modules containing Tamagui components which youll be using in your app. For example: if you are using the base Tamagui components. This directs the compiler to load and optimize.
`importsWhitelist`	`string[]`
Array of whitelisted file paths (always end in .js) which the compiler may parse at build-time. This usually is like ['constants.js', 'colors.js'], enabling extraction of any constant in those files
`logTimings`	`boolean`
Tamagui outputs information for each file it compiles on how long it took to run, how many components it optimized, and how many it flattened. Set to false to disable these logs.
`disableExtraction`	`boolean`
Disable extraction to CSS completely, instead fully relying on runtime. Setting this to true speed up development as generally your app will hot reload the Tamagui configuration itself.
`disableDebugAttr`	`boolean`
If enabled along with disableExtraction, all parsing will turn off. Normally turning off disableExtraction will keep the helpful debug attributes in DOM

Set up your theme

You'll want to create a tamagui.config.js (or ts) file at the root of your project that passes in a theme. For more documentation see Themes.

import { createTamagui } from 'tamagui'

const config = createTamagui({
  defaultTheme: 'light',
  shorthands: {
    px: 'paddingHorizontal',
  },
  themes: {
    light: {
      bg: '#fff',
      color: '#000'
    }
  },
  tokens: {
    // ... see Themes docus
  },
  media: {
    xs: { maxWidth: 660 },
    gtXs: { minWidth: 660 + 1 },
    sm: { maxWidth: 860 },
    gtSm: { minWidth: 860 + 1 },
    md: { minWidth: 980 },
    gtMd: { minWidth: 980 + 1 },
    short: { maxHeight: 820 },
    tall: { minHeight: 820 },
    hoverNone: { hover: 'none' },
    pointerCoarse: { pointer: 'coarse' },
  },
})

type Conf = typeof config

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

export default config

The createTamagui function receives a configuration object:

tokens: Use createTokens to generate variables in your theme and app.

theme: Define your design theme, which map to CSS properties.

media: Define reusable responsive media queries.

shorthands: Define any props you want to expand to style values, keys being the shorthand and values being the expanded style prop.

Add Provider

Import and use the Tamagui Provider component at the top component in your app.

import Tamagui from './tamagui.config'

export default function App() {
  return (
    <Tamagui.Provider>
      {/* The rest of your app here */}
    </Tamagui.Provider>
  )
}

Use any views

You're now ready to use Tamagui, import and use any components:

Button

import { Button } from 'tamagui'

export default function Demo() {
  return (
    <Button>Button</Button>
  )
}

Introduction

Configuration

Edit this page on GitHub.