getCSSVariable - Uniwind

Available in Uniwind 1.6.4+

Overview

Uniwind.getCSSVariable returns the value of one or more CSS variables on demand. Unlike useCSSVariable, it isn’t a hook, doesn’t subscribe to theme changes, and can be called from anywhere: event handlers, async functions, utility modules, or third-party callbacks where hooks aren’t allowed.

This function reads the value once. It will not update when the theme switches. If you need a reactive value inside a component, use useCSSVariable instead.

When to Use This Function

Reach for getCSSVariable when you need to:

Read a token from outside a React component (utility files, services, event handlers)
Resolve a value lazily inside an onPress, onLayout, or async callback
Pass a token into an imperative API that runs once (native module, animation driver, logger)
Access theme values from worklets or initialization code where hooks aren’t available

Prefer these alternatives when possible:

For styling components: Use the className prop directly
For reactive values inside components: Use useCSSVariable
For multiple style properties at once: Use useResolveClassNames

Usage

Basic Example

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

export const MyButton = () => (
  <Pressable
    onPress={() => {
      const primaryColor = Uniwind.getCSSVariable('--color-primary')

      console.log('Primary color is', primaryColor)
    }}
  >
    <Text>Press me</Text>
  </Pressable>
)

Multiple Variables at Once

Pass an array to read several variables in a single call:

import { Uniwind } from 'uniwind'

const reportTheme = () => {
  const [primaryColor, spacing, backgroundColor] = Uniwind.getCSSVariable([
    '--color-primary',
    '--spacing-4',
    '--color-background',
  ])

  analytics.track('theme_snapshot', { primaryColor, spacing, backgroundColor })
}

Outside of React

Because getCSSVariable is a plain function, you can call it from any module:

// utils/colors.ts
import { Uniwind } from 'uniwind'

export const getAccentColor = () => Uniwind.getCSSVariable('--color-accent')

import { getAccentColor } from './utils/colors'

const color = getAccentColor()

Making Variables Available

For getCSSVariable to resolve a value, the variable must be either:

Option 1: Used in a className (Recommended)

Use the variable at least once anywhere in your app’s className props:

<View className="bg-primary" />

This makes --color-primary available to getCSSVariable:

const primaryColor = Uniwind.getCSSVariable('--color-primary') // ✅ Works

Option 2: Define in Static Theme

If a variable is never used in any className but you still need it from JavaScript, define it in a static theme block in your global.css:

global.css

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

@theme static {
  --color-al-teal-75: #607d81;
  --chart-line-width: 2;
}

Then read it anywhere:

const tealColor = Uniwind.getCSSVariable('--color-al-teal-75') // ✅ Works
const lineWidth = Uniwind.getCSSVariable('--chart-line-width') // ✅ Works

Variables defined in @theme static are always available, even if they’re never used in any className.

Development Warnings

In development mode, Uniwind warns if you try to read a variable that isn’t available:

const unknownColor = Uniwind.getCSSVariable('--color-unknown')
// Console warning:
// "We couldn't find your variable --color-unknown. Make sure it's used
// at least once in your className, or define it in a static theme as
// described in the docs."

API Reference

Arguments

string | string[]

required

The name of the CSS variable(s) to read, including the -- prefix.

Single variable: Pass a string (e.g., '--color-primary')
Multiple variables: Pass an array of strings (e.g., ['--color-primary', '--spacing-4'])

Return Value

The return type depends on the input:

string | number | undefined

When passing a single string, returns the resolved value of the CSS variable:

Web: Always returns a string (e.g., "16px", "#ff0000")
Native: Returns string or number depending on the value type (e.g., 16, "#ff0000")
Undefined: If the variable cannot be found

Array<string | number | undefined>

When passing an array of strings, returns an array of resolved values in the same order:

const [color, spacing, radius] = Uniwind.getCSSVariable([
  '--color-primary',   // Returns: "#3b82f6"
  '--spacing-4',       // Returns: 16 (on native) or "16px" (on web)
  '--radius-lg'        // Returns: 12 (on native) or "12px" (on web)
])

Platform Differences

Web Platform

On web, getCSSVariable uses getComputedStyle() to retrieve values from the DOM. All values are returned as strings:

const color = Uniwind.getCSSVariable('--color-primary')
// Web: "#3b82f6" (string)

const [color, spacing] = Uniwind.getCSSVariable(['--color-primary', '--spacing-4'])
// Web: ["#3b82f6", "16px"] (strings)

Native Platform

On React Native, getCSSVariable accesses the internal variable store. Numeric values are returned as numbers:

const spacing = Uniwind.getCSSVariable('--spacing-4')
// Native: 16 (number)

const color = Uniwind.getCSSVariable('--color-primary')
// Native: "#3b82f6" (string)

const [color, spacing] = Uniwind.getCSSVariable(['--color-primary', '--spacing-4'])
// Native: ["#3b82f6", 16] (mixed types)

getCSSVariable vs useCSSVariable

	`getCSSVariable`	`useCSSVariable`
Where you can call it	Anywhere	Inside React components only
Reactive to theme changes	No	Yes
Triggers re-renders	No	Yes, when the theme changes
Best for	One-off reads, callbacks, utilities	Values rendered in JSX

If you only need a value once (e.g., inside an onPress handler), getCSSVariable avoids the extra subscription and re-render cost of useCSSVariable.

useCSSVariable

Reactive CSS variable access inside components

useResolveClassNames

Convert full className strings to style objects

Global CSS

Learn how to define CSS variables in your theme

Theming Basics

Understand how themes work in Uniwind

​Overview

​When to Use This Function

​Usage

​Basic Example

​Multiple Variables at Once

​Outside of React

​Making Variables Available

​Option 1: Used in a className (Recommended)

​Option 2: Define in Static Theme

​Development Warnings

​API Reference

​Arguments

​Return Value

​Platform Differences

​getCSSVariable vs useCSSVariable

​Related

useCSSVariable

useResolveClassNames

Global CSS

Theming Basics

Overview

When to Use This Function

Usage

Basic Example

Multiple Variables at Once

Outside of React

Making Variables Available

Option 1: Used in a className (Recommended)

Option 2: Define in Static Theme

Development Warnings

API Reference

Arguments

Return Value

Platform Differences

getCSSVariable vs useCSSVariable

Related