Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.uniwind.dev/llms.txt

Use this file to discover all available pages before exploring further.

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: 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

​
name
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:
​
single value
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 of values
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

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)
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

getCSSVariableuseCSSVariable
Where you can call itAnywhereInside React components only
Reactive to theme changesNoYes
Triggers re-rendersNoYes, when the theme changes
Best forOne-off reads, callbacks, utilitiesValues 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