Skip to main content


Stylable variables provide a way to define common values to be used across the stylesheet and exposed for sharing and theming. These variables are used only during build-time and have no runtime impact.

If you wish to use native dynamic variables, that can change value during runtime, see css custom properties for further details.


Use the :vars top level rule to define build variables.


To define a variable, add a variable declaration within a :vars ruleset.

:vars {
/* define x with value green */
x: green;

/* define y with value blue */
y: blue;


To get a variable value, use the value() function with the variable name as the first argument.

.a {
/* evaluate in declaration value */
color: value(x);

/* compose in declaration value */
background: url(a.jpg) no-repeat, url(b.jpg) repeat-x value(x);

/* set media params from a variable */
@media value(y) {}


Variables can be composed into a declaration value.

:vars {
x: green;

/* define y with the value green from x */
y: value(x);

/* define z with composed x value */
z: red, value(x), blue;


Use st-array to define a variable that holds a list of comma separated values that can be accessed by a zero-based index as the second argument to the value() function.

:vars {
/* comma separated list */
colors: st-array(red, green, blue);

.a {
/* access 2nd cell value */
color: value(colors, 1); /* green */


Use st-map to define a variable that holds key/value pairs with a space as a delimiter between them, and a comma separating each pair.

These values can then be accessed by providing the key as the second argument to the value() function.

:vars {
/* comma separated key/value pairs */
colors: st-map(
bg black,
text gold,

.a {
/* access 'text' key value */
color: value(colors, text); /* gold */

Import and Export

An exported build variable can be imported into another stylesheet with the @st-import at-rule.
@st-import [color1] from "./";

.a {
/* compose color1 to border value*/
border: 10px solid value(color1);


A build variable value can be accessed using the stVars mapping on the Stylable stylesheet runtime.

import { stVars } from './';

// map from local name to value
stVars.color1; // "green"
stVars['dashed-name']; // "blue"
local export only

Only build variables that are defined by the stylesheet are exported to Javascript - imported ones are not!

Custom variable


This API is not stable

Composed data structures like st-array and st-map can be defined from Javascript. Take a look at stBorder from the @stylable/custom-value to see how it works.

stBorder usage example
@st-import [stBorder] from "@stylable/custom-value";

:vars {
/* order of arguments: size style color */
myborder: stBorder(1px, solid, green);

.root {
border: value(myBorder); /* 1px solid green */
background-color: value(myBorder, color); /* green */