Skip to main content

Tamagui Custom Component Guidelines for React Native

Philosophy of Tamagui​

Tamagui is a cross-platform UI kit and style system for React Native and web. Its philosophy is to provide:

  • Consistent theming via tokens, palettes, and themes
  • Performance through atomic CSS and compile-time optimizations
  • Composable, type-safe components that are easy to extend
  • Design system scalability with palettes, variants, and shorthands

Colors, Palettes, and Themes​

  • Palettes are arrays of related colors (e.g., brand, gray) that provide a scale (e.g., $brand1 to $brand13).
  • Themes map palette tokens and custom values to semantic roles (e.g., background, primary, accent).
  • Tokens (like $brand6, $accent, $transparent) are used in components for consistency and easy theme switching.

Example Palette and Theme Setup​

const config = {
  palettes: {
    brand: [
      '#f5f3ff', '#ede9fe', '#c7d2fe', '#a5b4fc', '#818cf8', '#6366f1',
      '#4f46e5', '#4338ca', '#3730a3', '#312e81', '#1e1b4b', '#18181b', 'transparent',
    ],
  },
  themes: {
    brand: {
      background: '$brand12',
      primary: '$brand6',
      secondary: '$brand4',
      accent: '#f472b6',
      border: '#27272a',
      transparent: '$brand13',
    },
  },
}

Creating Custom Components​

  • Use styled() to extend Tamagui primitives (e.g., Button, Stack).
  • Add variants for different visual states (e.g., link, destructive).
  • Reference theme tokens for colors and spacing.

Example: Custom Button​

import { Button as TamaguiButton, styled } from 'tamagui'

const StyledButton = styled(TamaguiButton, {
  name: 'Button',
  variants: {
    link: {
      true: {
        bg: '$transparent',
        borderWidth: 0,
        color: '$primary',
        px: 0,
        py: 0,
        hoverStyle: { opacity: 0.7 },
        pressStyle: { opacity: 0.5 },
      },
    },
    destructive: {
      true: {
        bg: '$accent',
        color: '$background',
        hoverStyle: { opacity: 0.8 },
        pressStyle: { opacity: 0.6 },
      },
    },
  },
})

Best Practices​

  • Always use tokens for colors, spacing, and sizes.
  • Leverage palettes for scalable color systems.
  • Compose variants for flexible, reusable components.
  • Document your variants and tokens for team clarity.

Further Reading​

This guide is for developers building scalable, themeable UI with Tamagui in React Native projects. For more advanced patterns, see the official Tamagui documentation.