VarGroup<>

type VarGroup<Tokens extends {}>

A VarGroup is the type of the object that is generated as a result of calling stylex.defineVars. It maps keys to references to CSS custom properties.

VarGroup is also the required type for the first argument to stylex.createTheme

Usually, VarGroup is not needed explicitly, as it can be inferred from the argument to stylex.defineVars.

import * as stylex from '@stylexjs/stylex';

export const vars = stylex.defineVars({
  color: 'red',
  backgroundColor: 'blue',
});

export type Vars = typeof vars;
/*
  Vars = VarGroup<{
    color: string,
    backgroundColor: string,
  }>
*/

In some cases, however, VarGroup may be needed explicitly, to constrain the values of the variables within themes:

import * as stylex from '@stylexjs/stylex';
import type {VarGroup} from '@stylexjs/stylex';

const vars: VarGroup<{
  color: 'red' | 'blue' | 'green' | 'yellow',
  backgroundColor: 'red' | 'blue' | 'green' | 'yellow',
}> = stylex.defineVars({
  color: 'red',
  backgroundColor: 'blue',
});

Now when a theme for vars is being created, the values for color and backgroundColor can only be one of the specified values.

import * as stylex from '@stylexjs/stylex';
import {vars} from './vars.stylex';

export const theme1 = stylex.createTheme(vars, {
  color: 'red', // OK
  backgroundColor: 'blue', // OK
});

export const theme2 = stylex.createTheme(vars, {
  // Error: 'orange' is not assignable to 'red' | 'blue' | 'green' | 'yellow'
  color: 'orange', 
});

While, it's not needed in most cases, VarGroup also accepts an optional second type type argument.

Advanced use-case: unique type identity for a `VarGroup`

TypeScript (and Flow) use structural typing, which means that two objects with the same shape are considered to be the same type. However, each usage of stylex.defineVars results in a new set of variables.

It can be useful to have a unique type identity for each VarGroup created to be able to distinguish between them and accept themes for only a specific VarGroup. This is also known as "nominal typing" and can be achieved by using a unique symbol as the second type argument to VarGroup.

The complete type signature of VarGroup is:

type VarGroup<Tokens extends {}, ID extends symbol = symbol>

It can be used like this:

import * as stylex from '@stylexjs/stylex';
import type {VarGroup} from '@stylexjs/stylex';

type Shape = {
  color: string,
  backgroundColor: string,
};

declare const BaseColors: unique symbol;
export const baseColors: VarGroup<Shape, typeof BaseColors> =
  stylex.defineVars({
    color: 'red',
    backgroundColor: 'blue',
  });

declare const CardColors: unique symbol;
export const cardColors: VarGroup<Shape, typeof CardColors> =
  stylex.defineVars({
    color: 'red',
    backgroundColor: 'blue',
  });

Here baseColors and cardColors are VarGroup objects of the same shape, but with two distinct type identities. This ensures that a Theme for one can't be used with the other.

It should be rare that two separate VarGroup objects are defined with the same shape and so this feature is not needed in most cases. In the rare cases where it is needed, it is available.