Scoped Variables

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.

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

Usage

Basic Example

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.

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.

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

import { ScopedVariables } from 'uniwind'

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

Props

Record<string, string | number>

required

CSS variable overrides for this subtree. Every variable name must start with --; invalid names are ignored.

React.ReactNode

required

React children rendered inside the scoped variable boundary.

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.