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

# Scoped Variables

> Override CSS variables for a component subtree with `ScopedVariables`

## Overview

`ScopedVariables` overrides CSS variables for a specific subtree without changing the active theme or global variable values. Use it for component previews, branded sections, and local design-token overrides.

The nearest `ScopedVariables` value wins, so nested scopes inherit parent values and can override only what they need.

<Info>
  `ScopedVariables` is a runtime variable boundary. Class names, hooks, and `withUniwind`-wrapped components inside the boundary resolve variables from the scoped values first.
</Info>

## Usage

### Basic Example

```tsx theme={null}
import { ScopedVariables } from 'uniwind'
import { Text, View } from 'react-native'

export function Example() {
  return (
    <View className="gap-4">
      <View className="p-4 rounded-xl bg-primary">
        <Text className="text-white">Uses the active theme primary color</Text>
      </View>

      <ScopedVariables variables={{ '--color-primary': '#7c3aed' }}>
        <View className="p-4 rounded-xl bg-primary">
          <Text className="text-white">Uses a scoped purple primary color</Text>
        </View>
      </ScopedVariables>
    </View>
  )
}
```

### Nested Scoped Variables

Nested scopes merge with their parents. The closest value for each variable wins.

```tsx theme={null}
import { ScopedVariables } from 'uniwind'
import { Text, View } from 'react-native'

export function NestedScopes() {
  return (
    <ScopedVariables
      variables={{
        '--color-primary': '#7c3aed',
        '--color-secondary': '#f59e0b',
      }}
    >
      <View className="gap-3 p-4 rounded-xl bg-primary">
        <Text className="text-white">Purple primary from the outer scope</Text>

        <ScopedVariables variables={{ '--color-primary': '#059669' }}>
          <View className="p-4 rounded-lg bg-primary">
            <Text className="text-white">Green primary from the inner scope</Text>
            <Text className="text-secondary">Still inherits the amber secondary color</Text>
          </View>
        </ScopedVariables>
      </View>
    </ScopedVariables>
  )
}
```

### Reading a Scoped Variable in JavaScript

`useCSSVariable` reads the nearest scoped value and updates when the scope changes.

```tsx theme={null}
import { ScopedVariables, useCSSVariable } from 'uniwind'
import { Text, View } from 'react-native'

function PrimaryValue() {
  const primary = useCSSVariable('--color-primary')

  return <Text className="text-default">Primary: {String(primary)}</Text>
}

export function Example() {
  return (
    <ScopedVariables variables={{ '--color-primary': '#7c3aed' }}>
      <View className="p-4 rounded-xl bg-base">
        <PrimaryValue />
      </View>
    </ScopedVariables>
  )
}
```

## API Reference

### Component Signature

```tsx theme={null}
import { ScopedVariables } from 'uniwind'

<ScopedVariables variables={{ '--color-primary': '#7c3aed' }}>
  {/* scoped subtree */}
</ScopedVariables>
```

### Props

<ParamField path="variables" type="Record<string, string | number>" required>
  CSS variable overrides for this subtree. Every variable name must start with `--`; invalid names are ignored.
</ParamField>

<ParamField path="children" type="React.ReactNode" required>
  React children rendered inside the scoped variable boundary.
</ParamField>

## Behavior Notes

* `ScopedVariables` affects only its descendants and never mutates global theme variables.
* Nested scopes merge with parent scopes; the nearest value for a variable wins.
* Scoped values are used by `className`, `useCSSVariable`, `useResolveClassNames`, and `withUniwind`-wrapped components.
* On web, numeric values become pixel values. For example, `16` is applied as `16px`.
* The overridden variable should be defined in your theme or used by a class name, just like other CSS variables.

## Scoped Variables vs Other Theme APIs

* Use `ScopedVariables` to override one or more values for a subtree.
* Use [`ScopedTheme`](/api/scoped-themes) to apply an existing theme to a subtree.
* Use [`Uniwind.updateCSSVariables`](/theming/update-css-variables) to persistently update values for an entire theme at runtime.

## Related

<CardGroup cols={2}>
  <Card title="Scoped Themes" icon="palette" href="/api/scoped-themes">
    Apply an existing theme to a subtree
  </Card>

  <Card title="useCSSVariable" icon="code" href="/api/use-css-variable">
    Read CSS variables in JavaScript
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Update CSS Variables" icon="code" href="/theming/update-css-variables">
    Update variables for an entire theme at runtime
  </Card>

  <Card title="Global CSS" icon="css" href="/theming/global-css">
    Define CSS variables in your theme configuration
  </Card>
</CardGroup>