This article explains how to create and manage UI themes using the Godoteditor and its theme editor tool. We recommend getting familiar with thebasics behind GUI skinning/theming by reading Introduction to GUI skinning before starting.
The theme editor is a bottom panel tool that activates automatically, whena Theme resource is selected for editing. It containsthe necessary UI for adding, removing, and adjusting theme types and themeitems. It features a preview section for testing your changes live, as wellas a window dialog for doing bulk operations of the theme items.
Creating a theme¶
Like any other resources, themes can be created directly in the file system dockby right-clicking and selecting New Resource..., then selecting Themeand clicking Create. This is especially useful for creating project-widethemes.
Themes also can be created from any control node. Select a control node in the scenehierarchy, then in the inspector go to the theme property. From there you canselect New Theme.
This will create an empty theme and open up the theme editor. Keep in mind thatresources created this way are bundled with the scene by default. Use the contextmenu to save the new theme to a file instead.
While the theme editor provides the tools to manage theme types and items, themes alsoinclude the default, fallback font that you can edit only using the Inspector dock.Same applies to the contents of complex resource types, such as StyleBoxesand icons — they open for editing in the Inspector.
Theme editor overview¶
The theme editor has two main parts. The main theme editor, located at the bottom ofthe Godot editor, aims to provide users with tools to quickly create, edit, and deletetheme items and types. It gives visual tools for picking and changing controls, abstractingthe underlying theme concepts. The Manage Theme Items dialog, on the other hand,tries to address the needs of those who want to change themes manually. It's alsouseful for creating a new editor theme.
Theme previews¶
The left-hand side of the main editor has a set of preview tabs. The Default Previewtab is visible out of the box and contains most of the frequently used controls in variousstates. Previews are interactive, so intermediate states (e.g. hover) can be previewed as well.
Additional tabs can be created from arbitrary scenes in your project. The scenemust have a control node as its root to function as a preview. To add a new tabclick the Add Preview button and select the saved scene from your file system.
If you make changes to the scene, they will not be reflected in the previewautomatically. To update the preview click the reload button on the toolbar.
Previews can also be used to quickly select the theme type to edit. Select thepicker tool from the toolbar and hover over the preview area to highlight controlnodes. Highlighted control nodes display their class name, or type variation if available.Clicking on the highlighted control opens it for editing on the right-hand side.
Theme types and items¶
The right-hand side of the theme editor provides a list of theme types availablein the edited theme resource, and the contents of the selected type. The list oftype's items is divided into several tabs, corresponding to each data type availablein the theme (colors, constants, styles, etc.). If the Show Default option isenabled, then for each built-in type its default theme values are displayed, greyedout. If the option is disabled, only the items available in the edited theme itselfare displayed.
Individual items from the default theme can be added to the current theme byclicking on the Override button next to the item. You can also override allthe default items of the selected theme type by clicking on the Override Allbutton. Overridden properties can then be removed with the Remove Item button.Properties can also be renamed using the Rename Item button, and completelycustom properties can be added to the list using the text field below it.
Overridden theme items can be edited directly in the right-hand panel, unless theyare resources. Resources have rudimentary controls available for them, but must beedited in the Inspector dock instead.
Styleboxes have an unique feature available, where you can pin an individualstylebox from the list. Pinned stylebox acts like the leader of the pack, andall styleboxes of the same type are updated alongside it when you change itsproperties. This allows you to edit properties of several styleboxes at thesame time.
While theme types can be picked from a preview, they can also be added manually.Clicking the plus button next to the type list opens the Add item Type menu.In that menu you can either select a type from the list, or you can enter anarbitrary name to create a custom type. Text field also filters the list of controlnodes.
Manage and import items¶
Clicking the Manage Items button brings up the Manage Theme Items dialog. Inthe Edit Items tab you can view and add theme types, as well as view and editthe theme items of the selected type.
You can create, rename and remove individual theme items here by clicking thecorresponding Add X Item and specifying their name. You can also mass deletetheme items either by their data type (using the brush icon in the list) or bytheir quality. Remove Class Items will remove all built-in theme items youhave customized for a control node type. Remove Custom Items will remove allthe custom theme items for the selected type. Finally, Remove All Items willremove everything from the type.
From the Import Items tab you can import theme items from other themes. You canimport items from the default Godot theme, the Godot editor theme, or another customtheme. You can import individual or multiple items, and you can decide whether tocopy or omit their data as well. There are several ways you can select and deselect theitems, including by hand, by hierarchy, by data type, and everything. Opting toinclude the data will copy all theme items as they are to your theme. Omitting the datawill create the items of the corresponding data type and name, but will leave them empty,creating a template of a theme in a way.
