#Build a screen in UI Builder

This page makes a settings screen in UI Builder, shows it in a scene, and reads its values from code. Then it puts the screen in a window.

Video tutorial: Settings screen. All videos: Video tutorials.

#1. Make a UXML file

1. In the Project window, right-click a folder, then click Create > UI Toolkit > UI Document.
2. Name the file SettingsScreen.uxml.
3. Double-click the file. UI Builder opens it.

#2. Set up the canvas

1. In the Hierarchy of UI Builder, select the top item, SettingsScreen.uxml.
2. In the Inspector, under Canvas Size, select Match Game View. The canvas then has the size of the Game view.
3. In the toolbar of the Viewport, set the theme to Unity Default Runtime Theme.

The Toolbox controls add their theme and style sheets when they show, also in UI Builder. You do not add style sheets by hand.

#3. Find the controls

1. In the Library, click the Project tab.
2. Open Custom Controls (C#) > UI Toolbox.

The controls are in the same groups as in these documents: Inputs, Display, Overlays, Navigation, Data and charts, Layout, Settings, Windows and Workspace. Some controls are parts of another control, such as PieSlice in a PieChart or SidebarItem in a Sidebar. Put a part in its control.

#4. Add controls and set their attributes

1. Drag a Card from Display onto the canvas.
2. In the Inspector, set Title to Audio and Description to Sound and music.
3. Drag a Switch from Inputs into the card. Set Name to music and Label to Music.
4. Drag a Rating from Inputs into the card. Set Name to difficulty, Label to Difficulty and Max to 5.

Each attribute in the Inspector is a UXML attribute. The page of each control lists its attributes.

#5. Save

Press Ctrl+S (Cmd+S on macOS). UI Builder writes the UXML file. The file is plain text, so you can also edit it in a code editor:

<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:tb="UIToolbox">
  <tb:Card title="Audio" description="Sound and music">
    <tb:Switch name="music" label="Music" />
    <tb:Rating name="difficulty" label="Difficulty" max="5" />
  </tb:Card>
</ui:UXML>

#6. Show the screen in a scene

1. In the Hierarchy of the scene, right-click, then click UI Toolkit > UI Document.
2. Select the new GameObject. In the Inspector, give the UIDocument a Panel Settings asset.
3. Drag SettingsScreen.uxml into the Source Asset field of the UIDocument.
4. Press Play.

#7. Read the values from code

Find a control by its name with Q<T>. Add this component to the GameObject that has the UIDocument:

using UIToolbox;
using UnityEngine;
using UnityEngine.UIElements;

public class SettingsScreen : MonoBehaviour
{
    private void OnEnable()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;

        var music = root.Q<Switch>("music");
        music.RegisterValueChangedCallback(evt => Debug.Log($"Music: {evt.newValue}"));

        var difficulty = root.Q<Rating>("difficulty");
        difficulty.RegisterValueChangedCallback(evt => Debug.Log($"Difficulty: {evt.newValue}"));
    }
}

#8. Put the screen in a window

1. Open SettingsScreen.uxml in UI Builder.
2. From Windows, drag an Workspace onto the canvas. In the Inspector, under Flex, set Grow to 1, so the workspace fills the screen. On the canvas, the workspace shows a faint dashed outline and the name "Workspace". UI Builder does not save or restore the window session of the workspace.
3. Drag an Window into the workspace. Set Id to Settings, Title to Settings, Width to 360, Height to 240 and Initial Window State to open. The canvas shows the window with its title bar, at its initial position and size.
4. Drag the card into the window, on the canvas or in the Hierarchy of UI Builder.
5. Save and press Play. Drag the window by its title bar, and resize it by an edge.

To open and close the window from a button, add an WorkspaceToolbar in the workspace and an WorkspaceToolbarButton in the toolbar. Set the Window Id of the button to Settings. For all window attributes, see Create windows.

#What shows only in Play mode

UI Builder shows the layout and the styles. Some things happen only in Play mode:

• The workspace opens the windows that are not closed, and the windows move, resize, dock and animate. UI Builder draws each Window and WindowTemplateElement at its initial position and size, whatever its initial state, and each DockZone at its edge.
• Overlays such as Dialog, Drawer and MessageBox stay hidden until your code shows them. UI Builder shows them in place, so you can edit their content. To hide one while you edit the screen around it, set its Display to None in the Inspector; the overlay still shows when your code opens it. See Custom overlays (OverlayElement).
• Tooltips, keyboard shortcuts and gamepad input work.
• Controls that get their data from code, such as DataGrid and Graph, are empty.

#Next steps

• Make the scene objects and files with a wizard: Setup Wizard.
• See each control in use: Example scenes.
• Change colors, sizes and fonts: Theme variables.