updateCSSVariables

Available in Uniwind 1.1.0+

Overview

The updateCSSVariables method allows you to dynamically modify CSS variable values at runtime for a specific theme. This is useful for creating user-customizable themes, implementing dynamic color schemes, or adapting styles based on runtime conditions.

Variable changes are persisted per theme, so switching between themes will preserve the custom values you’ve set for each one.

When to Use This Method

Use updateCSSVariables when you need to:

Build user-customizable themes (e.g., custom accent colors, spacing preferences)
Implement dynamic brand theming (e.g., white-label apps)
Adjust theme colors based on runtime data (e.g., user preferences, A/B testing)
Create theme editors or design tools within your app
Adapt colors based on external factors (e.g., time of day, location)

For static theme customization, prefer defining variables directly in your global.css file using @theme and @variant directives.

Usage

Basic Example

import { Uniwind } from 'uniwind'

// Update a single variable for the light theme
Uniwind.updateCSSVariables('light', {
  '--color-primary': '#ff6b6b',
})

Multiple Variables at Once

import { Uniwind } from 'uniwind'

// Update multiple variables for the dark theme
Uniwind.updateCSSVariables('dark', {
  '--color-primary': '#4ecdc4',
  '--color-secondary': '#ffe66d',
  '--color-background': '#1a1a2e',
  '--spacing': 16,
})

User-Customizable Theme

import { Uniwind } from 'uniwind'
import { View, Button } from 'react-native'

export const ThemeCustomizer = () => {
  const applyCustomColors = (accentColor: string, backgroundColor: string) => {
    Uniwind.updateCSSVariables(Uniwind.currentTheme, {
      '--color-accent': accentColor,
      '--color-background': backgroundColor,
    })
  }

  return (
    <View className="p-4">
      <Button
        title="Ocean Theme"
        onPress={() => applyCustomColors('#0077be', '#e0f7fa')}
      />
      <Button
        title="Sunset Theme"
        onPress={() => applyCustomColors('#ff6b35', '#fff5e6')}
      />
      <Button
        title="Forest Theme"
        onPress={() => applyCustomColors('#2d6a4f', '#d8f3dc')}
      />
    </View>
  )
}

How It Works

updateCSSVariables modifies CSS variables for a specific theme and persists those changes. The variables you update can be:

Scoped theme variables: Variables defined inside @variant blocks (e.g., @variant light { --color-primary: ... })
Shared variables: Variables defined in @theme that are available across all themes

When you switch themes, your customized values are preserved and applied automatically.

Variable Persistence

// Customize the light theme
Uniwind.updateCSSVariables('light', {
  '--color-primary': '#ff6b6b',
})

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

// Switch back to light theme
Uniwind.setTheme('light')
// ✅ The custom --color-primary value is still applied

API Reference

Method Signature

Uniwind.updateCSSVariables(theme: string, variables: Record<string, string | number>): void

Parameters

string

required

The name of the theme to update. This should match a theme name defined in your global.css file (e.g., 'light', 'dark', or custom theme names).

Record<string, string | number>

required

An object mapping CSS variable names (with -- prefix) to their new values.

Keys: Must be valid CSS variable names starting with -- (validated in development mode)
Values: Can be strings (colors, units) or numbers (numeric values like spacing)

{
  '--color-primary': '#3b82f6',     // String color
  '--spacing': 16,             // Number (converted to px on web)
  '--radius-sm': 8,
}

Return Value

This method returns void. It updates the CSS variables immediately and triggers a re-render if the updated theme is currently active.

Platform Differences

Web Platform

On web, updateCSSVariables applies changes directly to the DOM using document.documentElement.style.setProperty():

Numeric values are automatically converted to pixel units (e.g., 16 becomes "16px")
String values are applied as-is
Changes take effect immediately
Updates trigger listener notifications if the modified theme is active

// Web behavior
Uniwind.updateCSSVariables('light', {
  '--spacing': 16,  // Applied as "16px"
  '--color-primary': '#3b82f6',  // Applied as "#3b82f6"
})

Native Platform

On React Native, updateCSSVariables updates the internal variable store with normalized values:

Color values are parsed and normalized to hex format using Culori
Numeric values are stored directly as numbers
Variables are added as getters to both UniwindStore.vars and theme-specific variable objects
Updates trigger listener notifications if the modified theme is active

// Native behavior
Uniwind.updateCSSVariables('light', {
  '--spacing': 16,  // Stored as 16
  '--color-primary': 'rgb(59, 130, 246)',  // Normalized to "#3b82f6"
})

Important Notes

CSS variable names must include the -- prefix. In development mode, Uniwind will validate this and warn you if you forget the prefix.

// ✅ Correct
Uniwind.updateCSSVariables('light', {
  '--color-primary': '#ff0000',
})

// ❌ Will show a warning in development
Uniwind.updateCSSVariables('light', {
  'color-primary': '#ff0000',  // Missing -- prefix
})

Updates only trigger component re-renders if the modified theme is currently active. Updating an inactive theme will store the changes but won’t cause immediate visual updates.

Making Variables Available

For updateCSSVariables to work with a CSS variable, the variable must be defined in your theme. There are two ways to ensure variables are available:

Option 1: Define in Theme Variants

Define variables inside @variant blocks in your global.css:

global.css

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

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

    @variant dark {
      --color-primary: #60a5fa;
      --color-background: #1f2937;
    }
  }
}

Now you can update these variables at runtime:

Uniwind.updateCSSVariables('light', {
  '--color-primary': '#ff0000',  // ✅ Works
})

Option 2: Define in Shared Theme

Define variables in @theme to make them available across all themes:

global.css

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

@theme {
  --color-brand-primary: #3b82f6;
  --color-brand-secondary: #8b5cf6;
  --spacing-custom: 24px;
}

These can be updated for any theme:

Uniwind.updateCSSVariables('light', {
  '--color-brand-primary': '#ff6b6b',  // ✅ Works
  '--spacing-custom': 32,  // ✅ Works
})

Performance Considerations

updateCSSVariables is optimized to only trigger re-renders when necessary. Updates to inactive themes don’t cause re-renders.

Keep in mind:

Changes are applied synchronously and take effect immediately
Only components using the updated variables will re-render (if the theme is active)
Updating variables frequently (e.g., on every slider drag) is fine, but consider debouncing for very rapid updates
Variables are stored per theme, so memory usage scales with the number of themes and customized variables

useCSSVariable

Read CSS variable values in JavaScript

Custom Themes

Learn how to create custom themes

Global CSS

Define CSS variables in your theme configuration

Theming Basics

Understand how themes work in Uniwind

​Overview

​When to Use This Method

​Usage

​Basic Example

​Multiple Variables at Once

​User-Customizable Theme

​How It Works

​Variable Persistence

​API Reference

​Method Signature

​Parameters

​Return Value

​Platform Differences

​Important Notes

​Making Variables Available

​Option 1: Define in Theme Variants

​Option 2: Define in Shared Theme

​Performance Considerations

​Related

useCSSVariable

Custom Themes

Global CSS

Theming Basics

Overview

When to Use This Method

Usage

Basic Example

Multiple Variables at Once

User-Customizable Theme

How It Works

Variable Persistence

API Reference

Method Signature

Parameters

Return Value

Platform Differences

Important Notes

Making Variables Available

Option 1: Define in Theme Variants

Option 2: Define in Shared Theme

Performance Considerations

Related