Skip to main content

​
Overview

The useCSSVariable hook allows you to retrieve CSS variable values directly in JavaScript. It’s particularly useful when you need to access theme colors, spacing values, or other design tokens programmatically for calculations, animations, or third-party library configurations.
This hook should be used sparingly. For most styling use cases, prefer using the className prop with Tailwind utilities.

​
When to Use This Hook

Use useCSSVariable when you need to:
  • Access theme colors for third-party libraries (e.g., chart libraries, map markers)
  • Perform calculations with design tokens (e.g., dynamic positioning based on spacing values)
  • Configure native modules that require color/size values
  • Pass theme values to JavaScript animation libraries
  • Access design tokens for runtime logic
Prefer these alternatives when possible:
  • For styling components: Use the className prop directly
  • For multiple style properties: Use useResolveClassNames
  • For third-party components: Wrap them with withUniwind

​
Usage

​
Basic Example

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

export const MyComponent = () => {
  const primaryColor = useCSSVariable('--color-primary')
  const spacing = useCSSVariable('--spacing-4')

  return (
    <View className="p-4">
      <Text>Primary color: {primaryColor}</Text>
      <Text>Spacing: {spacing}</Text>
    </View>
  )
}

​
With Chart Libraries

import { useCSSVariable } from 'uniwind'
import { LineChart } from 'react-native-chart-kit'

export const ThemedChart = () => {
  const primaryColor = useCSSVariable('--color-primary')
  const backgroundColor = useCSSVariable('--color-background')
  const textColor = useCSSVariable('--color-foreground')

  return (
    <LineChart
      data={chartData}
      width={300}
      height={200}
      chartConfig={{
        backgroundColor: backgroundColor,
        backgroundGradientFrom: backgroundColor,
        backgroundGradientTo: backgroundColor,
        color: () => primaryColor,
        labelColor: () => textColor,
      }}
    />
  )
}

​
Accessing Custom Theme Variables

import { useCSSVariable } from 'uniwind'
import MapView, { Marker } from 'react-native-maps'

export const ThemedMap = () => {
  const markerColor = useCSSVariable('--color-accent')

  return (
    <MapView>
      <Marker
        coordinate={{ latitude: 37.78, longitude: -122.4 }}
        pinColor={markerColor}
      />
    </MapView>
  )
}

​
Making Variables Available

For the hook to resolve a CSS variable, the variable must be either: Use the variable at least once anywhere in your app’s className props: 
// Somewhere in your app
<View className="bg-primary" />
This makes --color-primary available to useCSSVariable: 
const primaryColor = useCSSVariable('--color-primary') // ✅ Works

​
Option 2: Define in Static Theme

If you have CSS variables that are never used in classNames but need to be accessed in JavaScript, define them in a static theme block in your global.css:
global.css
@import 'tailwindcss';
@import 'uniwind';

@theme static {
  --color-al-teal-10: #eaeeee;
  --color-al-teal-25: #cad4d5;
  --color-al-teal-75: #607d81;
  --color-al-teal-100: #2b5257;

  --color-custom-teal-10: #eaeeee;
  --color-custom-teal-25: #cad4d5;
  --color-custom-teal-75: #607d81;
  --color-custom-teal-100: #2b5257;

  --chart-line-width: 2;
  --chart-dot-radius: 4;
}
Then access them anywhere: 
const tealColor = useCSSVariable('--color-al-teal-75') // ✅ Works
const lineWidth = useCSSVariable('--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 will warn you if you try to access a variable that hasn’t been made available: 
const unknownColor = useCSSVariable('--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."
If you see this warning, either use the variable in a className somewhere or add it to @theme static in your global.css.

​
API Reference

​
Arguments

​
name
string
required
The name of the CSS variable to retrieve, including the -- prefix (e.g., --color-primary, --spacing-4).

​
Return Value

​
value
string | number | undefined
The resolved value of the CSS variable. The type depends on the platform:
  • 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

​
Platform Differences

On web, useCSSVariable uses getComputedStyle() to retrieve values from the DOM. All values are returned as strings:
const color = useCSSVariable('--color-primary')
// Web: "#3b82f6" (string)
On React Native, useCSSVariable accesses the internal variable store. Numeric values are returned as numbers:
const spacing = useCSSVariable('--spacing-4')
// Native: 16 (number)

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

​
Performance Considerations

The useCSSVariable hook is reactive and will automatically update when the theme changes, ensuring your values stay in sync with the active theme.
Keep in mind:
  • The hook subscribes to theme changes, so components will re-render when themes switch
  • For static values that don’t need theme reactivity, consider storing them outside the component
  • Accessing many variables in a single component is fine, but consider grouping related logic

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

withUniwind

Wrap third-party components to add className support