Why is my USS class selector not applying styles in Unity UI Toolkit?

The most common cause is a name mismatch between the USS selector and the actual class on the VisualElement. USS class selectors use a dot prefix (.my-class) and are case-sensitive. Check that AddToClassList was called with the exact same string, that the USS file is referenced by the UXML or added via styleSheets.Add, and that no higher-specificity selector is overriding your rule.

How does selector specificity work in USS?

USS specificity follows CSS rules: type selectors (VisualElement, Button) have the lowest specificity, class selectors (.my-class) are higher, name selectors (#my-name) are highest. When multiple rules target the same element, the more specific rule wins. If specificity ties, the rule declared later in the file wins. Inline styles set via C# always override USS rules.

How do I debug which USS styles are applied to a VisualElement?

Use the UI Toolkit Debugger (Window > UI Toolkit > Debugger). Select the target element in the tree view to see all applied styles, which USS selectors matched, computed values, and the class list. The Matching Selectors panel shows every rule that applies and their specificity order. This is equivalent to browser DevTools for web CSS debugging.

Fix: Unity UI Toolkit USS Selector Not Matching

Quick answer: USS selectors fail to match when class names have typos (they are case-sensitive), the USS file is not linked to the UXML or UIDocument, a higher-specificity selector overrides yours, or you are using a type selector name that does not match the C# class name. Use the UI Toolkit Debugger to inspect applied styles and matching selectors in real time.

Here is how to fix Unity UI Toolkit USS selectors not matching. You write a USS rule targeting .my-button, add the class to your element in UXML, and the style does not apply. The element renders with default styling as if your USS file does not exist. No error in the console, no warning, just silent failure. USS debugging is subtle because unlike CSS in browsers, Unity does not have obvious DevTools built into every workflow — you need to know where to look.

The Symptom

A USS style rule does not visually affect the targeted VisualElement. The element appears with default or inherited styles instead of the values defined in your USS file. This can affect class selectors (.my-class), type selectors (Button), name selectors (#my-element), or complex selectors with combinators.

The USS file has no syntax errors (Unity would log a warning for invalid USS). The file is in the project. But the styles simply do not appear on the element.

What Causes This

Class name mismatch. USS class selectors are case-sensitive and must match exactly. .MyButton does not match an element with class mybutton or my-button. UXML class attributes and C# AddToClassList calls must use the identical string as the USS selector (minus the dot prefix).

USS file not linked. The USS file must be referenced either in the UXML via <Style src="...">, added to a ThemeStyleSheet, or applied via element.styleSheets.Add() in C#. Simply having the file in the project does nothing — it must be explicitly associated with the visual tree that contains your element.

Specificity override. A more specific selector elsewhere (perhaps in Unity’s default theme or another USS file loaded earlier) overrides your rule. Type selectors lose to class selectors, which lose to name selectors. If Unity’s built-in theme has a Button type selector rule, your Button type selector with the same specificity may be overridden depending on load order.

Wrong type selector name. Type selectors in USS use the C# class name, not a tag name. For built-in elements: Button, Label, TextField, VisualElement, ScrollView. For custom elements, use your exact C# class name. If you created class MyCustomButton : Button, the type selector is MyCustomButton, not Button.

Pseudo-class state not active. Selectors like .my-button:hover only apply when the element is actually in that state. If you are checking in the editor Scene view without hovering, the style will not show.

The Fix

Step 1: Verify the class is actually on the element. Use the UI Toolkit Debugger to inspect the element and confirm the class list.

// Debug: print all classes on an element
VisualElement element = root.Q<Button>("submit-btn");
foreach (string cls in element.GetClasses())
{
    Debug.Log("Class: " + cls);
}

Step 2: Ensure the USS file is linked. In UXML, add a Style reference at the top of the document. In C#, add the stylesheet to the element or a parent.

<!-- In UXML -->
<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <Style src="MyStyles.uss" />
    <ui:Button class="primary-btn" text="Click Me" />
</ui:UXML>

// In C# — add stylesheet programmatically
var styleSheet = Resources.Load<StyleSheet>("MyStyles");
rootVisualElement.styleSheets.Add(styleSheet);

Step 3: Increase selector specificity. If a default theme rule overrides yours, make your selector more specific by combining a type selector with a class selector.

/* Low specificity — may be overridden */
.primary-btn {
    background-color: #2196F3;
}

/* Higher specificity — type + class */
Button.primary-btn {
    background-color: #2196F3;
}

/* Highest without !important — name + class */
#submit-btn.primary-btn {
    background-color: #2196F3;
}

Step 4: Use the UI Toolkit Debugger. Open Window > UI Toolkit > Debugger. Pick the UIDocument in the scene, navigate the visual tree, and select your element. The “Matching Selectors” panel shows every USS rule that applies, their source file, and specificity order. This immediately reveals if another rule is winning.

Common Naming Pitfalls

Unity recommends BEM-style naming for USS classes: block__element--modifier. Avoid camelCase in USS class names because it is easy to introduce case mismatches. Use lowercase with hyphens: .inventory-slot--selected rather than .inventorySlotSelected.

/* BEM naming in USS */
.card { padding: 8px; }
.card__title { font-size: 16px; }
.card--highlighted { border-color: #FFD700; }

“USS is CSS without DevTools open by default. The UI Toolkit Debugger is your DevTools — use it the moment a selector does not match.”

Runtime vs Editor Differences

USS files loaded in the editor via EditorWindow use a different style resolution path than runtime UIDocument components. Theme stylesheets may differ between editor and runtime contexts. If styles work in a custom editor window but not in a runtime UIDocument, check that the same USS file is referenced in both contexts and that the runtime PanelSettings has the correct theme assigned.

When a USS selector does not match, it is almost always a spelling issue or a missing stylesheet link. Open the Debugger and look at the class list — the answer is right there.