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:
PropTypeDefault
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>
)
}