Theming Basics - Uniwind

Overview

Uniwind provides a powerful theming system that allows you to create beautiful, consistent user interfaces that adapt to user preferences. By default, Uniwind includes three pre-configured themes: light, dark, and system.

Default Themes

Uniwind pre-registers three themes out of the box, so you can start using them immediately without any configuration.

Available Themes

Theme	Description
`light`	Light theme
`dark`	Dark theme
`system`	Automatically follows the device’s system color scheme preferences

Light and Dark Themes

If you only need light and dark themes, you’re all set! Uniwind automatically registers these themes for you, and you can start using theme-based class variants immediately:

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

export const ThemedComponent = () => (
  <View className="bg-white dark:bg-gray-900 p-4">
    <Text className="text-gray-900 dark:text-white">
      This text adapts to the current theme
    </Text>
  </View>
)

System Theme

The system theme is a special theme that automatically syncs with your device’s color scheme. When enabled, your app will automatically switch between light and dark themes based on the user’s device settings.

Using the system theme provides the best user experience, as it respects the user’s device-wide preferences.

Default Configuration

Here are the default values that Uniwind uses for theming:

themes

Array<string>

The list of available themes.Default:

['light', 'dark', 'system']

adaptiveThemes

boolean

Whether themes automatically adapt to the device’s color scheme.Default:

true

initialTheme

string

The theme that’s applied when the app first launches.Default:

'light' | 'dark'

Automatically determined based on your device’s current color scheme.

Changing Themes

You can programmatically change the active theme at runtime using the setTheme function.

Switch to a Specific Theme

import { Uniwind } from 'uniwind'

// Switch to dark theme
Uniwind.setTheme('dark')

// Switch to light theme
Uniwind.setTheme('light')

When you set the theme to light or dark, Uniwind automatically calls React Native’s Appearance.setColorScheme. This ensures native components like Alert, Modal, and system dialogs match your app’s theme.

Switching from system to light or dark disables adaptive themes. The app will stay on the selected theme even if the device color scheme changes.

Enable System Theme

To enable automatic theme switching based on the device’s color scheme:

import { Uniwind } from 'uniwind'

// Enable system theme (adaptive themes)
Uniwind.setTheme('system')

Setting the theme to system re-enables adaptive themes, allowing your app to automatically follow device color scheme changes.

Creating a Theme Switcher

Here’s a complete example of a theme switcher component:

import { View, Pressable, Text } from 'react-native'
import { Uniwind, useUniwind } from 'uniwind'

export const ThemeSwitcher = () => {
  const { theme, hasAdaptiveThemes } = useUniwind()

  const themes = [
    { name: 'light', label: 'Light', icon: '☀️' },
    { name: 'dark', label: 'Dark', icon: '🌙' },
    { name: 'system', label: 'System', icon: '⚙️' },
  ]
  const activeTheme = hasAdaptiveThemes ? 'system' : theme

  return (
    <View className="p-4 gap-4">
      <Text className="text-sm text-gray-600 dark:text-gray-300">
        Current: {activeTheme}
      </Text>

      <View className="flex-row gap-2">
        {themes.map((t) => (
          <Pressable
            key={t.name}
            onPress={() => Uniwind.setTheme(t.name)}
            className={`
              px-4 py-3 rounded-lg items-center
              ${activeTheme === t.name
                ? 'bg-blue-500'
                : 'bg-gray-200 dark:bg-gray-700'
              }
            `}
          >
            <Text className="text-2xl mb-1">{t.icon}</Text>
            <Text
              className={`text-xs ${
                activeTheme === t.name
                  ? 'text-white'
                  : 'text-gray-900 dark:text-white'
              }`}
            >
              {t.label}
            </Text>
          </Pressable>
        ))}
      </View>
    </View>
  )
}

Accessing Theme Information

Uniwind exposes a global object that provides information about the current theme state.

Runtime Theme Information

You can access theme information programmatically:

import { Uniwind } from 'uniwind'

// Get the current theme name
console.log(Uniwind.currentTheme) // e.g., 'light', 'dark', or 'system'

// Check if adaptive themes are enabled
console.log(Uniwind.hasAdaptiveThemes) // e.g., true or false

Using the useUniwind Hook

For React components, use the useUniwind hook to access theme information and automatically re-render when the theme changes:

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

export const ThemeDisplay = () => {
  const { theme, hasAdaptiveThemes } = useUniwind()

  return (
    <View className="p-4">
      <Text className="text-lg font-bold">
        Current theme: {theme}
      </Text>
      <Text className="text-sm text-gray-600 dark:text-gray-300 mt-1">
        {hasAdaptiveThemes ? 'Following system theme' : 'Fixed theme'}
      </Text>
    </View>
  )
}

API Reference

Uniwind Global Object

setTheme

(themeName: string) => void

Changes the active theme at runtime.Parameters:

themeName: The name of the theme to activate ('light', 'dark', 'system', or a custom theme name)

currentTheme

string

The name of the currently active theme.Returns: 'light', 'dark', 'system', or a custom theme name

hasAdaptiveThemes

boolean

Indicates whether adaptive themes are currently enabled.Returns: true if adaptive themes are enabled, false otherwise

updateCSSVariables

(theme: string, variables: Record<string, string | number>) => void

Dynamically updates CSS variables at runtime for a specific theme.Parameters:

theme: The name of the theme to update ('light', 'dark', or a custom theme name)
variables: An object mapping CSS variable names (with -- prefix) to their new values

For detailed usage examples and platform-specific behavior, see the updateCSSVariables documentation.

Using Theme Variants in ClassNames

Apply different styles based on the active theme using the dark: variant:

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

export const Card = () => (
  <View className="
    bg-white dark:bg-gray-800
    border border-gray-200 dark:border-gray-700
    p-6 rounded-lg
    shadow-sm dark:shadow-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 content adapts to the theme automatically
    </Text>
  </View>
)

Best Practices

Use semantic color names: Instead of hardcoding colors, define theme-aware color tokens in your Tailwind config for better consistency.

Test both themes: Always test your UI in both light and dark themes to ensure proper contrast and readability.

Avoid theme-specific logic in components: Let the styling system handle theme switching. Keep your component logic theme-agnostic.

Custom Themes

Learn how to create custom themes beyond light and dark

useUniwind Hook

Access theme information in your React components

Global CSS

Define global CSS variables for your themes

Update CSS Variables

Dynamically update CSS variables at runtime

Style Based on Themes

Advanced theme-based styling techniques

​Overview

​Default Themes

​Available Themes

​Light and Dark Themes

​System Theme

​Default Configuration

​Changing Themes

​Switch to a Specific Theme

​Enable System Theme

​Creating a Theme Switcher

​Accessing Theme Information

​Runtime Theme Information

​Using the useUniwind Hook

​API Reference

​Uniwind Global Object

​Using Theme Variants in ClassNames

​Best Practices

​Related

Custom Themes

useUniwind Hook

Global CSS

Update CSS Variables

Style Based on Themes

Overview

Default Themes

Available Themes

Light and Dark Themes

System Theme

Default Configuration

Changing Themes

Switch to a Specific Theme

Enable System Theme

Creating a Theme Switcher

Accessing Theme Information

Runtime Theme Information

Using the useUniwind Hook

API Reference

Uniwind Global Object

Using Theme Variants in ClassNames

Best Practices

Related