Toolbar - regular search field

UI Builder

About UI Builder ->

UI Builder allows visual creation of UI assets in UI Toolkit, and is available as a built-in feature {2021.1 and later} or a package {2020.3 and earlier}

When to use

• Use a toolbar search field to enable users quickly locate an Asset or a Scene Object
• If the search query of the database (Asset Library / Scene Objects) needs to be categorized by type, use a toolbar pop-up search field

When to use a condensed search field

• Use a condensed search field to simplify the UI when search is not the primary functionality in the area
• The condensed search field usually reduces discoverability of the search functionality compared to the regular search field: consider whether this reduced discoverability is worth the trade-off for a more simplified UI

Style

Search fields appear in toolbars and follow the same principles as other toolbar controls.

Toolbar controls

For more information go to Components > Toolbar controls ->

Length of field

Search field in minimum width

Recommended minimum width:
To allow for legible user input, the recommended minimum width for search fields are 150 px, or 20 characters.

Condensed search field styling

Condensed search field styled in a few different contexts

The condensed search field in its collapsed state adapts its styling to the context in which it appears, matching the appearance of other icon buttons in the area.

Behavior

Search results

Searching for a crate texture in Project library

Search results of a query is displayed immediately while a user is typing.

Search filters

Hierarchy toolbar popup search field is displaying object type filters

Toolbar pop-up search fields allows users to set object type filters for their search query with a dropdown menu.

Expand and collapse

In its collapsed state, the condensed search field appears as an icon button with a search icon. Clicking on the search button expands the condensed search field into a regular search field and a collapse button, and automatically places focus on the search field.
‍
Clicking on the collapse button collapses the condensed search field back into its collapsed state. If the search field is empty, clicking outside of the search field removes focus from it and automatically collapses it. If there is input in the search field, clicking outside of the Search Field does not automatically collapse it.

Covering or pushing surrounding UI

If space allows, the expansion of the condensed search field should push surrounding UI away. If there is little space in the UI, the expanded search field may cover surrounding UI, as it is considered a transient state.

Anatomy and layout

Anatomy

Anatomy of a toolbar search field and toolbar popup search field and its key parts

A search field can contain following elements:
‍‍
1. Search / popup search icons
2. Clear icon
3. Body (container)
4. User input
5. Filter label (popup search fields)
6. Popup menu
7. Condensed search button
8. Collapse button

1. Search / Popup search icons

Pop-up search icon is used to open the dropdown menu.

2. Clear icon

Used to clear user input.

3. Body (container)

The body of the search field is the container where content (icons, user input, filter label) is displayed.

4. User input

The search query input by the user inside the search field.

5. Filter label

Label of the selected filter in pop up search fields.

6. Pop-up menu

7. Condensed search button

Condensed state of the condensed search field appears as an icon button.

8. Collapse button

Collapse button used to collapse a condensed search field from its expanded state.

Interaction states

Toolbar search field in its interactive states

Default

Default state of a search field.

Hover

When hovering over a search field body the border will be highlighted. Additionally, the user’s default cursor will switch to a line cursor glyph to indicate the nature of the element.

Focused

When a search field enters the focused state its content will be highlighted in addition to its borders. This is because the content is being selected, allowing for the user to interact with it immediately (for example by immediately deleting or copying all of it).

Placeholder text

For the regular search field, placeholder text inside the search field disappears upon user focus.

For the condensed search field, placeholder text inside the search field should stay in the field upon user focus, only disappearing upon user input. This enables the user to see the placeholder text even when the expansion of the search field automatically places focus on it.

Disabled

A search field that is disabled will indicate so by having its body “greyed out” and will not accept inputs or react to hovering.

Condensed search field in its collapsed and expanded states

Collapsed

A collapsed condensed search field appears as a search icon button.

Expanded

A search field that is disabled will indicate so by having its body “greyed out” and will not accept inputs or react to hovering.

Color

1. icon 2. text 3. input_field-border 4. input_field-background

1. icon

Variable name

Variable description

Light theme

Dark theme

Primary Icon Color

Icons that do not require to be color coded uses this color

#555555

#C4C4C4

Icon color palette

For information about icon color use go to Foundations > Iconography ->

Editor color palette

For general concepts about color use go to Foundations > Color Palette ->

UI Toolkit samples

Go to Window > UI Toolkit > Samples, to view code samples in C# / USS / UXML.

Code references

Scripting references for

UI Toolkit

ToolbarSearchField

Unity - Scripting API:
ToolbarSearchField

docs.unity3d.com

ToolbarPopupSearchField

Unity - Scripting API:
ToolbarPopupSearchField

docs.unity3d.com