USS custom properties (variables)

USS variables, also called custom properties, define values that you can reuse in other USS rules. You can create variables for any type of USS property.

To create a USS variable, prefix its name with a double-hyphen (--).

--color-1: red;

To use a USS variable value in another USS rule, use the var() function to call it.

var(--color-1);

Note:
The var() function also accepts an optional default value (see Specifying default values below).

After you define a variable, you can use it in as many other USS properties as you want. When you update it, all of the USS properties that use it update as well.

For example, the following USS snippet defines one style rule that declares two color variables, and two style rules that use those variables.

:root {
  --color-1: blue;
  --color-2: yellow;
}

.paragraph-regular {
  color: var(--color-1);
  background: var(--color-2);
  padding: 2px;
  }

.paragraph-reverse {
  color: var(--color-2);
  background: var(--color-1);
  padding: 2px;
  }

To update the color scheme, you only have to change the two variable values instead of four color values.

Variables make it easier to manage styles for complex UI, where multiple rules, sometimes in different style sheets, use the same values.

Specifying default values

The var() function accepts an optional default value. The UI system uses the default value when it cannot resolve the variable. For example, if you remove a variable from a style sheet but forget to remove a reference to it.

To specify a default value for a variable, add it after the variable value, separated by a comma ,. The following USS snippet calls the --color-1 variable, but if the UI system can’t resolve it, it uses the hex value for red (#FF0000).

var(--color-1, #FF0000);

Built-in Unity variables

Unity’s built-in style sheets define USS variables that set default values for the Editor interface. You can use these variables in your own style sheets to ensure that your custom Editor extensions match Unity style. For details, see [Built-in Unity variables](UIE-USS-UnityVariables.

Differences from CSS

Variables work almost exactly the same way in USS as they do in CSS. For detailed information about CSS variables, see the MDN documentation.

There are some minor differences that are important to understand.

Calling USS variables from other functions

Some web browsers support using the var() function inside of other functions, as in the property declaration below:

background-color: rgb(var(--red), 0, 0);

Unity does not support this use of var().

Declaring variables in the root selector

A common CSS practice is to declare “global” variables in the :root pseudo-class selector. Because every element in a web page inherits from :root, every selector in a CSS style sheet can call variables declared there.

In Unity, declaring variables in :root works for Editor windows and runtime panels, provided you attach the stylesheet to the root Visual Element of the panel or Editor window. It does not work for Inspector UI.

In the Inspector, the :root pseudo class is only active on the Inspector window’s root VisualElement. The subtrees you attach style sheets to are much lower in the Inspector hierarchy. Consequently, the :root selector never matches any part of a subtree.

Simulating :root for custom Inspector UI

You can use a USS class selector as a substitute for the :root selector in custom Inspectors. Create a USS class to declare your variables in, and apply it to the highest element in the hierarchy to which you have access.

For example, the following USS snippet defines the following classes:

• .root declares a variable.
• .label1 calls the variable.

.root {
    --color1: rgb(25, 255, 75);
}

.label1 {
    color: var(--color1);
}

The following UXML snippet creates a simple container element and assigns the root class to it. The container has a child element, a Label, with the label1 class assigned to it.

In the UXML:

<UXML xmlns="UnityEngine.UIElements">
    <VisualElement class="root">
        <!-- Including, for example... -->
        <Label class="label1" text="Label text"/>
    </VisualElement>
</UXML>

Because the Label inherits from the container, its styles can call any variables defined in the container’s styles.