Best practices for USS

Follow these best practices when you write USS to style visual elements.

Avoid inline styles

Use USS files instead of inline styles when you can for more efficient memory usage.

Inline styles are per element and can cause memory overhead. When you use inline styles in a C# script or a UXML file on many elements, the memory usage becomes high quickly.

Selector architecture consideration

All USS selectors are applied at runtime so the architecture affects initialization performance. USS selectors are applied when an element first appears or when its classes change:

• The :hover selector is the main culprit for selectors to cause interactivity issues and a re-styling.
• The performance impact appears under the Update Styling in the Profiler.

Usually, it’s not a problem if you have a lot of selectors because each USS file is turned into a lookup table. However, the performance decreases linearly as you add classes to an element. Each class in the list is used to query the lookup table. The complexity is N1 x N2, where:

• N1 is the number of class on the element
• N2 is the current number of applicable USS files

The number of elements in the hierarchy is the main fact that affects performance. Update Styling might be negligible for simple UIs but is significant for large UIs that have several thousands of elements. If an element matches a lot of selectors, it causes overhead to merge the styles coming from each rule.

Complex selectors hierarchy guidelines

In general, complex selectors have more impact on performance than simple selectors. Complex selectors depend on the ancestors of an element to match it. When possible, consider the following:

• If you want to have partial match, use the child selector (selector1 > selector2 > selector3) instead of the descendant selector (selector1 selector2 selector3).
• Avoid using universal selector at the end of complex selectors (selector1 > selector2 > *) or the combination of descendant selector with the universal selector (selector1 * selector2). The universal selector tests every potential element against the selector which can impact performance.
• Avoid using :hover pseudo-class in selectors on elements with many descendants, such as .yellow:hover > * > Button. Mouse movements invalidate the entire hierarchy of elements targeted by an :hover selector.

Use BEM to improve performance

You can use the Block Element Modifier(BEM) convention to reduce hierarchical selectors. With BEM, each element receives a class that combines its specific existence inside another element.

About BEM

BEM は Block Element Modifier の略です。BEM はシンプルなシステムで、構造化され、あいまいでない、メンテナンスが簡単なセレクターを作成するのに役立ちます。BEM では、要素にクラスを割り当て、それらのクラスをスタイルシートのセレクターとして使用します。

BEM クラスには最大 3 つのコンポーネントがあります。

• ブロック名: ブロックは意味のあるスタンドアロンのエンティティまたは制御です。例: menu、button、list-view
• 要素名: スタンドアロンの意味を持たず、意味的にそのブロックに関連付けられているブロックの一部。要素名は 2 つのアンダースコアを使ってブロック名に追加されます。例: menu**item、 button**icon、list-view__item
• モディファイア: ブロックや要素の外観や動作を変更するフラグ。モディファイアは 2 つのダッシュを使ってブロックまたは要素名に追加されます。例: menu--disabled、menu**item--disabled、button--small、list-view**item--selected

名前の各部分は、アルファベット文字、数字、ダッシュで構成されます。名前の各部分は、ダブルアンダースコア __ またはダブルダッシュ -- でつながれます。

The following example shows UXML code for a menu:

<VisualElement class="menu">
    <Label class="menu__item" text="Banana" />
    <Label class="menu__item" text="Apple" />
    <Label class="menu**item menu**item--disabled" text="Orange" />
</VisualElement>

Each element is equipped with classes that describe its role and appearance, you can write most of your selectors with only one class name:

.menu {
}

.menu__item {
}

.menu__item--disabled {
}

You can style elements with a single class name. Sometimes, you might need to use complex selectors. For example, you can use a complex selector when the style of an element depends on the modifier of its block:

.button {
}

.button__icon {
}

.button--small {
}

.button--small .button__icon {
}

ノート:

• Avoid specifying long selectors. A long selector could indicate inconsistencies in the graphic design of your UI.
• Avoid using type names (Button, Label) or element names (#my-button) in your BEM selectors.

Make visual elements BEM-friendly

UI Toolkit は BEM に準拠しています。各ビジュアル要素には、必要なクラス名が付けられています。例えば、すべての TextElement には、 unity-text-element クラスがあります。TextElement から派生した Button の各インスタンスは、そのクラスリストに unity-button と unity-text-element クラスが含まれます。

VisualElement またはその子孫の 1 つから新しい要素を派生させる場合は、以下のガイドラインに従って、BEM 手法を使用して要素のスタイルを簡単に設定できます。

• コンストラクターで AddToClassList() を使用して、関連する USS クラスを要素インスタンスに追加します。
• 新しい要素がコンストラクターで子要素をインスタンス化する場合は、関連するクラスを子に割り当てます。例: my-block**first-child、my-block**other-child
• 要素が複数の状態やバリアント (小さいや大きいなど) をサポートする場合は、要素の状態が変化するときや要素のバリアントが選択されるときに、関連するクラスを追加、または、削除します。
• If you use the element in other projects, consider prefixing your classes to avoid conflicts with existing user class names.

その他の参考資料

• Introduction to USS
• USS selectors