Unity style sheets (USS)

Each VisualElement includes style properties that set the dimensions of the element and how the element is drawn on screen, such as backgroundColor or borderColor.

Style properties are either set in C# or from a style sheet. Style properties have their own data structure (IStyle interface).

UI Toolkit supports style sheets written in USS (Unity style sheet). USS files are text files inspired by Cascading Style Sheets (CSS) from HTML. The USS format is similar to CSS, but USS includes overrides and customizations to work better with Unity.

This section includes details on USS, its syntax, and its differences when compared to CSS.

For a quick reference of supported USS properties, see the USS properties reference.

Definition of a Unity style sheet

The fundamental building blocks of a Unity style sheet (USS) are as follows :

• USS is a text file recognized as an asset. The text file must have the .uss extension.
• USS only supports style rules.
• Style rules are composed of a selector and a declaration block.
• The selector identifies which visual element the style rule affects.
• The declaration block, enclosed by curly braces, contains one or more style declarations. Each style declaration is comprised of a property and a value. Each style declaration ends with a semi-colon.
• The value for each style property is a literal which, when parsed, must match the target property name.

The general syntax of a style rule is :

selector {
  property1:value;
  property2:value;
}

Attaching USS to visual elements

You can attach a Unity style sheet (USS) to any visual element. Style rules apply to the visual element and all its descendants. Style sheets are also re-applied automatically when necessary.

Load StyleSheet objects with standard Unity APIs such as AssetDatabase.Load() or Resources.Load(). Use the VisualElement.styleSheets.Add() method to attach style sheets to visual elements.

If you modify a USS file while the EditorWindow is running, style changes are applied immediately.

The process of style application is transparent to a developer using UI Toolkit. Style sheets are re-applied automatically when needed (hierarchy changes, stylesheet reload).

Style matching with rules

When you define a style sheet, you can apply it to a Visual Tree. Selectors match against elements to resolve which properties apply from the USS file. If a selector matches an element, the style declarations apply to the element.

For example, the following rule matches any Button object:

Button {
  width: 200px;
}

VisualElement matching

UI Toolkit uses the following criteria to match a visual element with its style rule:

• Its C# class name (always the most derived class).
• A name property that’s a string.
• A class list represented as a set of strings.
• The ancestry and position of the VisualElement in the visual tree.

These traits can be used in selectors in the style sheet.

If you are familiar with CSS you can see the similarity with the HTML tag name, the id attribute and class attribute.