Stylable Variables

Use variables to define common values to be used across the stylesheet and so they can be exposed for sharing and theming. These variables are used only during build-time and have no impact on the resulting runtime code.

If you wish to use dynamic variables, and to change their values during runtime, see css custom properties (vars) for further details.

important

Variables are scoped to the specific stylesheet and do not conflict with variables from another stylesheet.

Use in stylesheet

Use the syntax :vars to define variables, and apply them with a value():

@namespace "Example1";
:vars {
    color1: red;
    color2: green;
}
.root {
    color: value(color1);
    background: value(color2);
}

/* CSS output */
.Example1__root {
    color: red; /* color1 */
    background: green; /* color2 */
}

Import variables

Any var defined in a stylesheet is exported as a named export and can be imported by other stylesheets.

@namespace "Example2";
@st-import [color1, color2] from "./example1.st.css";

.root {
    border: 10px solid value(color1);
}
.root:hover {
    border: 10px solid value(color2);
}

/* CSS output */
.Example2__root {
    border: 10px solid red; /* color1 */
}
.Example2__root:hover {
    border: 10px solid green; /* color2 */
}

important

Imported variables are not exported from the stylesheet that has imported them. They can be imported only from the stylesheet in which they are declared.

Compose variables

You can set the value of a variable using another variable.

@namespace "Example3";
@st-import [color1, color2] from "./example1.st.css";

:vars {
    border1: 10px solid value(color1); /* use color1 in a complex value */
}
.root {
    border: value(border1); /* user border1 */
}

/* CSS output */
.Example3__root {
    border: 10px solid red; /* 10px solid {color1} */
}

Advanced variable types

You can use Stylable custom types when defining a variable to group multiple values under a shared context. This gives you a better way to define and manage variables in your stylesheet.

Stylable does this by utilizing a type function in the variable definition and passing additional arguments to the value() function.

Stylable native variable types

By default, Stylable exposes two types of variables that are available globally and do not require a special import:

• st-map
• st-array

st-map

Use the st-map function to provide an interface similar to a map. You can group variables by context and retrieve them by key.

Its definition is comprised of key/value pairs with a space as a delimiter between them, and a comma as a separator between pairs.

:vars {
    colors: st-map(
        bg green,
        text red
    );
}

.root {
    background-color: value(colors, bg); /* green */
}

st-array

Use the st-array function to provide an interface which is similar to an array. This enables you to group variables by context and retrieve them by their index.

Its definition is comprised of values that are zero-based and comma separated.

:vars {
    colors: st-array(red, green);
}

.root {
    background-color: value(colors, 1); /* green */
}

Custom variable type

Stylable also offers a custom variable type, stBorder, that must be imported from the @stylable/custom-value package.

stBorder accepts three arguments, size, style and color in that order. When using the type, you can either invoke the entire border definition (by not passing an additional argument), or specific parts of it, according to their key.

@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 */
}

note

stBorder is just the first of future custom variable types that will be available in Stylable.