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 tamagui
, the complete set of components designed to build universal apps. It's fully tree-shakeable, so your bundler should only add components you import.
If you'd rather build your own design system on top of core you'd just swap out tamagui
for @tamagui/core
. See the Design Systems guide for more on how to configure Core.
Quick Start
Try out create-tamagui for a helpful starter template which comes with @tamagui/shorthands
and @tamagui/theme-base
for easy default configuration:
npm create tamagui@latest
This gives you everything pre-configured for full-stack apps with shared code.
Install
yarn add tamagui
Be sure to set the environment variable TAMAGUI_TARGET
to the string web
or native
, respectively. You can usually just do this in your package.json script, swapping out the command for whichever bundler you use:
{"scripts": {"dev": "TAMAGUI_TARGET=web webpack"}}
If you're targeting a native app and installing tamagui
(not core), you'll need to set up expo-linear-gradient
first as Metro will try and find it even if you don't import it.
Config file
Create a tamagui.config.ts
file at the root of your project.
You can import createTamagui
from either tamagui
or @tamagui/core
depending on which you decide to use.
From there you'll export default the result of createTamagui
like so:
import { shorthands } from '@tamagui/shorthands'import { themes, tokens } from '@tamagui/theme-base'import { createFont, createTamagui } from 'tamagui'export default createTamagui({themes,tokens,shorthands,fonts: {body: createFont({family: 'Arial',size: {// You'll want to fill these values in so you can use them// for now, fontSize="$4" will be 14px.// You can define different keys, but `tamagui`// standardizes on 1-15.4: 14,},lineHeight: {4: 16,},}),},})
You'll need to install these packages if you want the Tamagui pre-configured design system:
yarn add @tamagui/shorthands @tamagui/theme-base
For an even quicker start, you can get a full design system with @tamagui/config-base
, which we show on the Configuration page. That page also goes into more detail on everything createTamagui
accepts.
Root export
Import and use the TamaguiProvider
component as the top component in your app.
// this provides some helpful reset styles to ensure a more consistent lookimport '@tamagui/core/reset.css'import React, { Suspense } from 'react'import { TamaguiProvider } from 'tamagui'import config from './tamagui.config'export default function App() {return (<TamaguiProvider config={config}>{/* if you want nice React 18 concurrent hydration, you'll want Suspense near the root */}<Suspense><AppContents /></Suspense></TamaguiProvider>)}
TamaguiProvider has optional props, see the docs for them here.
Done!
You're now ready to use Tamagui, import and use any components:
import { Button } from 'tamagui'export default function Demo() {return <Button>Button</Button>}
We recommend spending time understanding configuration from here, skipping over the Compiler setup. The compiler is optional and should be saved for setting up after you've built something you'd like to test it with.