Migrate from Immediate Mode GUI (IMGUI) to UI Toolkit

This guide is for developers experienced with Immediate Mode GUI (IMGUI) to migrate to UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary Toolkit. This guide focuses on the Editor UI, but its information can also apply to the runtime UI as well.

Key differences

Code-driven versus UI-driven

IMGUI is code-driven by calls to the OnGUI function in an C# script which implements it. UI Toolkit provides more options for Editor UI creation. With UI Toolkit, you define the behaviors in C# scriptsA piece of code that allows you to create your own Components, trigger game events, modify Component properties over time and respond to user input in any way you like. More info
See in Glossary. However, when defining UI elements and styles, in addition to C#, you can visually define UI controls in UI Builder or write in an XML-like text file (called UXML) directly. For more information, see Simple UI Toolkit workflow.

Immediate versus retained mode

With IMGUI, you describe the UI tree when the UI is repainted within the OnGUI() function. You must call this function when an event enters the UI or when you repaint the UI. There is no persistent information pertaining the UI tree between different events. Whereas, you create visual elementsA node of a visual tree that instantiates or derives from the C# VisualElement class. You can style the look, define the behaviour, and display it on screen as part of the UI. More info
See in Glossary with UI Toolkit in a tree structure called Visual TreeAn object graph, made of lightweight nodes, that holds all the elements in a window or panel. It defines every UI you build with the UI Toolkit.
See in Glossary. Information in the Visual Trees is retained persistently.

Constant versus state changes

IMGUI is based around the OnGUI() function that runs at least once every frame. You define the look and the behaviors of the UI for every possible frame. The body of OnGUI() might contain many conditions and different states.

UI Toolkit operates in an event-driven system. You define the look of the UI in its default state and define the behaviors of the UI in response to events. Any changes you make in UI Toolkit cause persistent changes to the state of your UI.

For example, the declaration of a button in IMGUI looks like the following:

if (GUILayout.Button("Click me!"))
{
    //Code runs here in frames where the user clicks the button.

    //Code makes changes to the UI for frames where the user has just clicked the button.
}
else
{
    //Code specifies what happens in all other frames.
}

The example above looks like the following in UI Toolkit:

UIDocument document = GetComponent<UIDocument>();

//Create button.
Button button = new Button();
button.text = "Click me!";

//Set up event handler.
button.RegisterCallback<ClickEvent>((ClickEvent evt) =>
{
    //Code runs here after button receives ClickEvent.
});

//Add button to UI.
document.rootVisualElement.Add(button);

For a completed example on how to create a custom Editor window with UI Toolkit, see Simple UI Toolkit workflow.

IMGUI support

Use the IMGUIContainer to place IMGUI code inside of a VisualElement. Everything you can do inside of OnGUI() is supported.

You can arrange multiple IMGUIContainers and lay them out by mixing GUILayout and UI Toolkit layouts. Note that it’s not possible to add VisualElement instances inside of an IMGUIContainer.

From IMGUI to UI Toolkit conversion

The following table lists the equivalent functions between IMGUI and UI Toolkit:

The following table lists the equivalent methods, classes, attributes between IMGUI and UI Toolkit:

Additional resources

• Get started with UI Toolkit
• Unity style sheets (USS)
• Examples
• IMGUI events