Font Definition - ZoboUI Docs

The Font Definition utility allows you to specify custom fonts for the text of UI elements. This utility leverages the -unity-font-definition USS property to set the font.

Adding Custom Fonts

You can add custom fonts in the Font Definition utility under the Utilities section of the Theme Config asset.

We expect most people will want to use the file picker to select Font Assets. However, you can also add fonts by providing a custom string value. This is useful if you want to reference a variable, url, or resource in your USS. Learn more about the values Unity expects.

How to Add Fonts

Create or import your desired Font Asset within your Unity project.
Navigate to the Theme Config Asset and select the Font Definition utility.
Click the + button to add a new item to the list. Assign a key to each font, which will be used to generate the class name. If you entered sans or serif as the key, for instance, it would generate the following classes: font-sans or font-serif.
Choose the font from your assets for each key.
Click the Generate button to create new classes for each added font.

Example: Using Custom Fonts

Once you have generated the classes for your custom fonts, you can apply them to UI elements. For example, to use a font named Inter, add a class font-inter to a VisualElement:

<ui:VisualElement class="font-inter">
    <ui:Label text="This is text with the Inter font." />
</ui:VisualElement>

Customize

Modifier Variations

You can customize which modifier variations of the Font Definition utility are generated, such as pseudo-classes (e.g., hover, focus) and custom modifiers.

By default, no modifier variations are defined for the Font Definition utility.

By fine-tuning the utility variations, you maintain control over your stylesheet's size and complexity, ensuring that only necessary styles are included. To update these values:

Open the Theme Config Asset: Find the asset within your Unity project.
Navigate to the 'Utilities' Section: Locate the Font Definition utility.
Adjust Modifier Variations: Select which modifiers you want to be generated for the utility. Keep in mind that the order of the modifiers will affect the order and specificity of the generated USS classes.

Class Tags and Properties

The Font Definition utility generates classes based on predefined tags and their associated USS properties. While we recommend keeping these defaults for consistency and ease of reference in our documentation, you have the option to customize them to suit your project's specific needs.

These values are prepended to the defined values in this format tag-{value}. If a tag is empty, the generated class will simply be the value by itself.

Here are the default tags and the USS properties they set for the Font Definition utility:

font : -unity-font-definition

To customize these tags and properties, you can edit the Tag Property Map field for the Font Definition utility in the Theme Config asset. This allows you to define new tags or modify existing ones, thus tailoring the generated classes to your preferences.

Extending Core Fields

The Font Definition utility does not extend any fields from the Core section of the Theme Config asset. Before you try to extend any fields, we recommend checking Unity's documentation to verify which types of values are expected by the relevant USS properties.

To customize or define these extended fields:

Open the Theme Config Asset: Locate the asset within your Unity project.
Navigate to the 'Utilities' Section: Find the Font Definition utility.
Customize Extend Fields: Modify or add fields in the Extend Fields array to change the core configuration values that are extended. You'll only be able to extend fields of the same type.

Disable Utility

The Font Definition utility is enabled by default. You can disable it by unchecking the Enabled option in the Theme Config asset. This will prevent the generation of the utility's styles.