Style Based on Themes

Overview

Uniwind provides two approaches for creating theme-aware styles: using theme variant prefixes (like dark:) or defining CSS variables with @layer theme. Each approach has its use cases and benefits.

Approach 1: Theme Variant Prefixes

The simplest way to style components based on themes is using the dark: variant prefix.

Basic Usage

By default, styles apply to all themes:

import { View } from 'react-native'

// This red background applies to both light and dark themes
<View className="bg-red-500" />

Add theme-specific styles using the dark: prefix:

import { View } from 'react-native'

// Red in light mode, darker red in dark mode
<View className="bg-red-500 dark:bg-red-600" />

Multiple Theme-Specific Styles

You can combine multiple theme-aware utilities:

import { View, Text } from 'react-native'

export const Card = () => (
  <View className="
    bg-white dark:bg-gray-900
    border border-gray-200 dark:border-gray-700
    shadow-sm dark:shadow-lg
    p-4 rounded-lg
  ">
    <Text className="
      text-gray-900 dark:text-white
      text-lg font-bold
    ">
      Card Title
    </Text>
    <Text className="
      text-gray-600 dark:text-gray-300
      mt-2
    ">
      Card description with theme-aware colors
    </Text>
  </View>
)

When to Use Theme Variant Prefixes

Best for: One-off styling, prototyping, or small components where you want explicit control over light and dark mode colors.

Pros:

Explicit and easy to understand
No setup required
Full control over each theme’s appearance
Works great for small apps or prototypes

Cons:

Verbose for larger apps
Requires repeating dark: prefix for many properties
Difficult to maintain consistent colors across components
Doesn’t scale well to 3+ themes

Approach 2: CSS Variables with @layer theme

For larger applications, defining theme-specific CSS variables provides a more scalable and maintainable solution.

Setting Up CSS Variables

Define your theme variables in global.css:

global.css

@import 'tailwindcss';
@import 'uniwind';

@layer theme {
  :root {
    @variant dark {
      --color-background: #000000;
      --color-foreground: #ffffff;
      --color-card: #1f2937;
      --color-border: #374151;
      --color-muted: #6b7280;
    }

    @variant light {
      --color-background: #ffffff;
      --color-foreground: #000000;
      --color-card: #ffffff;
      --color-border: #e5e7eb;
      --color-muted: #9ca3af;
    }
  }
}

Using CSS Variables

Reference your variables directly in components:

import { View, Text } from 'react-native'

export const Card = () => (
  <View className="bg-card border border-border p-4 rounded-lg">
    <Text className="text-foreground text-lg font-bold">
      Card Title
    </Text>
    <Text className="text-muted mt-2">
      Card description that automatically adapts to the theme
    </Text>
  </View>
)

bg-background automatically resolves to #ffffff in light theme and #000000 in dark theme. No dark: prefix needed!

When to Use CSS Variables

Best for: Medium to large applications, design systems, or apps with consistent color palettes across many components.

Pros:

Clean, maintainable code
Consistent colors across the entire app
Easy to update themes in one place
Scales well to any number of themes
Semantic naming improves code readability

Cons:

Requires initial setup
Less explicit than variant prefixes
Need to define all variables upfront

Supporting Multiple Themes

CSS variables make it easy to support unlimited custom themes:

global.css

@layer theme {
  :root {
    @variant dark {
      --color-background: #000000;
      --color-foreground: #ffffff;
      --color-primary: #3b82f6;
    }

    @variant light {
      --color-background: #ffffff;
      --color-foreground: #000000;
      --color-primary: #3b82f6;
    }

    @variant ocean {
      --color-background: #0c4a6e;
      --color-foreground: #e0f2fe;
      --color-primary: #06b6d4;
    }

    @variant sunset {
      --color-background: #7c2d12;
      --color-foreground: #fef3c7;
      --color-primary: #f59e0b;
    }
  }
}

Components using these variables automatically work with all themes:

import { View, Text } from 'react-native'

export const ThemedComponent = () => (
  <View className="bg-background p-4">
    <Text className="text-foreground">
      This component works with light, dark, ocean, and sunset themes!
    </Text>
    <View className="bg-primary mt-4 p-2 rounded">
      <Text className="text-background">Primary action</Text>
    </View>
  </View>
)

To register additional themes, follow the Custom Themes guide.

Migration Guide

From Theme Variants to CSS Variables

Identify repeated colors across your components
Define CSS variables for these colors in global.css
Replace theme variants with CSS variable references
Test thoroughly in all themes

Example migration:

// Before: Using theme variants
<View className="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-700">
  <Text className="text-gray-900 dark:text-white">Hello</Text>
</View>

// After: Using CSS variables
<View className="bg-card border border-border">
  <Text className="text-foreground">Hello</Text>
</View>

Theming Basics

Learn the fundamentals of theming in Uniwind

Global CSS

Configure global styles and CSS variables

Custom Themes

Create custom themes beyond light and dark

useUniwind Hook

Access theme information in your components

Getting started

API

Theming

Style Based on Themes

Overview

Approach 1: Theme Variant Prefixes

Basic Usage

Multiple Theme-Specific Styles

When to Use Theme Variant Prefixes

Approach 2: CSS Variables with @layer theme

Setting Up CSS Variables

Using CSS Variables

When to Use CSS Variables

Supporting Multiple Themes

Migration Guide

From Theme Variants to CSS Variables

Theming Basics

Global CSS

Custom Themes

useUniwind Hook

​Overview

​Approach 1: Theme Variant Prefixes

​Basic Usage

​Multiple Theme-Specific Styles

​When to Use Theme Variant Prefixes

​Approach 2: CSS Variables with @layer theme

​Setting Up CSS Variables

​Using CSS Variables

​When to Use CSS Variables

​Supporting Multiple Themes

​Migration Guide

​From Theme Variants to CSS Variables

​Related

Theming Basics

Global CSS

Custom Themes

useUniwind Hook

Overview

Approach 1: Theme Variant Prefixes

Basic Usage

Multiple Theme-Specific Styles

When to Use Theme Variant Prefixes

Approach 2: CSS Variables with @layer theme

Setting Up CSS Variables

Using CSS Variables

When to Use CSS Variables

Supporting Multiple Themes

Migration Guide

From Theme Variants to CSS Variables

Related