DEV Community

Cathy Lai
Cathy Lai

Posted on

Getting Started with Tamagui: A Complete Guide to Modern React Native Styling

#reactnative #design #mobile #tutorial

Transform your React Native app with Tamagui's powerful design system and component library

Introduction

Tamagui is a modern, performant design system for React Native that brings the power of CSS-in-JS to mobile development. With its intuitive API, design tokens, and excellent TypeScript support, Tamagui makes building beautiful, consistent UIs a breeze.

In this tutorial, we'll walk through installing Tamagui in a React Native Expo project and create a beautiful text-heavy screen to demonstrate its capabilities.

What You'll Learn

  • How to install and configure Tamagui in a React Native Expo project
  • Setting up the necessary configuration files
  • Creating beautiful typography with Tamagui's design tokens
  • Building a responsive layout with proper spacing and colors
  • Best practices for organizing your Tamagui components

Prerequisites

  • Basic knowledge of React Native and Expo
  • Node.js and npm/yarn installed
  • An existing React Native Expo project

Step 1: Installation

First, let's install the core Tamagui dependencies:

# Core Tamagui packages
npm install @tamagui/core @tamagui/config @tamagui/animations-react-native

# Additional components
npm install @tamagui/text 

# Development dependencies
npm install --save-dev @tamagui/babel-plugin @tamagui/metro-plugin
Enter fullscreen mode Exit fullscreen mode

Step 2: Configuration Files

Babel Configuration

Update your babel.config.js to include the Tamagui babel plugin:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      'expo-router/babel',
      [
        '@tamagui/babel-plugin',
        {
          components: ['@tamagui/core'],
          config: './tamagui.config.ts',
        },
      ],
    ],
  };
};
Enter fullscreen mode Exit fullscreen mode

Metro Configuration

Update your metro.config.js to handle Tamagui's transformations:

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

const config = getDefaultConfig(__dirname);

module.exports = withTamagui(config, {
  components: ['@tamagui/core'],
  config: './tamagui.config.ts',
});
Enter fullscreen mode Exit fullscreen mode

Tamagui Configuration

Create a tamagui.config.ts file in your project root:

import { createTamagui } from '@tamagui/core'
import { config } from '@tamagui/config/v3'

const tamaguiConfig = createTamagui(config)

export default tamaguiConfig

export type Conf = typeof tamaguiConfig

declare module '@tamagui/core' {
  interface TamaguiCustomConfig extends Conf {}
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Setting Up the Provider

Wrap your app with the TamaguiProvider in your root layout file:

// app/_layout.tsx
import { TamaguiProvider } from '@tamagui/core';
import config from '../tamagui.config';

export default function RootLayout() {
  return (
    <TamaguiProvider config={config}>
      {/* Your existing app content */}
    </TamaguiProvider>
  );
}
Enter fullscreen mode Exit fullscreen mode

Step 5: Understanding Tamagui's Design Tokens

Tamagui uses a sophisticated design token system that provides:

Typography Scale

  • $1 to $15: Font sizes that scale responsively
  • $lineHeight: Line height tokens for better readability
  • $fontWeight: Consistent font weights

Color System

  • $gray1 to $gray12: Neutral colors (light to dark)
  • $blue1 to $blue12: Brand colors with proper contrast
  • Semantic colors like $color, $background, $border

Spacing System

  • $1 to $10: Consistent spacing scale
  • $space: Predefined spacing values
  • $radius: Border radius tokens

Step 6: Best Practices

1. Use Semantic Tokens 

// ❌ Avoid hardcoded values
<Text fontSize={16} color="#333333" />

// ✅ Use design tokens
<Text fontSize="$4" color="$gray12" />
Enter fullscreen mode Exit fullscreen mode

2. Leverage Component Variants 

<Text variant="heading" size="large">
  Beautiful Heading
</Text>
Enter fullscreen mode Exit fullscreen mode

3. Organize Your Components 

// Create reusable styled components
const ArticleTitle = styled(Text, {
  fontSize: '$8',
  fontWeight: '700',
  color: '$gray12',
  lineHeight: '$8',
});
Enter fullscreen mode Exit fullscreen mode

Step 7: Running Your App

After completing the setup, restart your development server:

npx expo start --clear
Enter fullscreen mode Exit fullscreen mode

Conclusion

Tamagui provides a powerful, modern approach to React Native styling. With its design token system, excellent TypeScript support, and comprehensive component library, it's an excellent choice for building scalable, maintainable mobile applications.

Top comments (0)