> ## 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.

# getCSSVariable

> Read CSS variable values from outside of React components

<Badge>Available in Uniwind 1.6.4+</Badge>

## Overview

`Uniwind.getCSSVariable` returns the value of one or more CSS variables on demand. Unlike [`useCSSVariable`](/api/use-css-variable), 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.

<Warning>
  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`](/api/use-css-variable) instead.
</Warning>

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

<Tip>
  **Prefer these alternatives when possible:**

  * For styling components: Use the `className` prop directly
  * For reactive values inside components: Use [`useCSSVariable`](/api/use-css-variable)
  * For multiple style properties at once: Use [`useResolveClassNames`](/api/use-resolve-class-names)
</Tip>

## Usage

### Basic Example

```tsx theme={null}
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:

```tsx theme={null}
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:

```ts theme={null}
// utils/colors.ts
import { Uniwind } from 'uniwind'

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

```tsx theme={null}
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:

```tsx theme={null}
<View className="bg-primary" />
```

This makes `--color-primary` available to `getCSSVariable`:

```tsx theme={null}
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`:

```css global.css theme={null}
@import 'tailwindcss';
@import 'uniwind';

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

Then read it anywhere:

```ts theme={null}
const tealColor = Uniwind.getCSSVariable('--color-al-teal-75') // ✅ Works
const lineWidth = Uniwind.getCSSVariable('--chart-line-width') // ✅ Works
```

<Info>
  Variables defined in `@theme static` are always available, even if they're never used in any `className`.
</Info>

## Development Warnings

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

```tsx theme={null}
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

<ParamField path="name" type="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']`)
</ParamField>

### Return Value

The return type depends on the input:

<ParamField path="single value" type="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
</ParamField>

<ParamField path="array of values" type="Array<string | number | undefined>">
  When passing an **array of strings**, returns an array of resolved values in the same order:

  ```tsx theme={null}
  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)
  ])
  ```
</ParamField>

## Platform Differences

<Accordion title="Web Platform" icon="globe">
  On web, `getCSSVariable` uses `getComputedStyle()` to retrieve values from the DOM. All values are returned as strings:

  ```tsx theme={null}
  const color = Uniwind.getCSSVariable('--color-primary')
  // Web: "#3b82f6" (string)

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

<Accordion title="Native Platform" icon="mobile">
  On React Native, `getCSSVariable` accesses the internal variable store. Numeric values are returned as numbers:

  ```tsx theme={null}
  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)
  ```
</Accordion>

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

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

## Related

<CardGroup cols={2}>
  <Card title="useCSSVariable" icon="code" href="/api/use-css-variable">
    Reactive CSS variable access inside components
  </Card>

  <Card title="useResolveClassNames" icon="code" href="/api/use-resolve-class-names">
    Convert full className strings to style objects
  </Card>

  <Card title="Global CSS" icon="css" href="/theming/global-css">
    Learn how to define CSS variables in your theme
  </Card>

  <Card title="Theming Basics" icon="palette" href="/theming/basics">
    Understand how themes work in Uniwind
  </Card>
</CardGroup>