Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Overview

test-test
Standard text field with a label in light and dark themes
  • A text field is a basic text control that enables the user to type text
  • They typically appear in forms like the Inspector or Settings windows

Text field variations

Text fields in UIT framework vs IMGUI framework.
Text fields in UIT framework vs IMGUI framework.
Text fields: UIT vs IMGUI
  • Text fields in the UIT framework are for both single or multiple lines of text
  • IMGUI includes both text fields for single lines of text and text areas for multiple text lines

Text field (UI Toolkit)

When to use

Used for single-line or multi-line text inputs; enabled by the Multiline option in UI Builder.

UI Builder text field icon
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}
API in

UI Toolkit

TextField
Reference for a text field with multiple lines
Text field (IMGUI)
When to use

Used for single-line text inputs.

API in

IMGUI

EditorGUILayout.TextField
Makes a single-line text field
Text area (IMGUI)
When to use

Used to allow a scalable, dynamic input box for multiple lines of text.

API in

IMGUI

EditorGUILayout.TextArea
Makes a text field with multiline support

Guidance

When to use

  • When users require the option to enter text, the text field component and text area component can both be used depending on the framework
  • Multiple lines of text can be entered by the user in scalable, dynamic text boxes if room for large amounts of text are needed; dynamic text fields provide a scalable view for editing and review
  • Text strings are often used to identify or assign an object, as seen in the name field of an object in the Inspector header

Style

Length of field

  • The maximum recommended width of a text field is 300 px; text fields wider than 300 px have reduced readability
  • Consider the amount of text users will likely enter when setting a minimum / maximum character limit

Inset / outset borders

Like all input fields, a text field appears as an inset slot or box where the user can add text.
Unity Editor uses accented borders to promote control differentiation and help users visually scan the UI faster.

A labeled image showing the different usage of inset and outset borders.
1. Inset Borders are used with input groups, such as text fields, in or beneath the component surface.
2. Outset Borders are used with action groups, such as dropdowns, on top of the component surface.

Behavior

Multiline behavior
  • In the UI Toolkitframework a text field has unlimited length by default unless maxLength has been defined as any number other than 0
  • In the IMGUI framework, a text field restricts their view to a standard dimension, causing content to scroll if it exceeds the element’s dimensions

Text fields with multi-line enabled in UI Toolkit(or text area in IMGUI) should be resizable, adapting to both the quantity of text they contain and user actions

Delayed fields
  • Only use delayed fields in cases that require the control to be confirmed (for example, by pressing Enter or by changing keyboard focus) to finalize the value
  • Only use delayed fields if changing the property requires time to process, or if the change of the property is destructive; otherwise, use non-delayed versions of these fields that immediately change the property value as the user is typing/manipulating it
Icon displaying the Unity logo
EditorGUI.
DelayedTextField

EditorGUI.Delayed
TextField

docs.unity3d.com

Arrow icon indicating link goes to an external source
Keyboard interactions
  • Pressing return inserts a new line
  • Pressing shift + return confirms and finishes entry of the text
  • Pressing esc cancels current entry and reverts the field to the value it was before editing began
Relative height

The recommended maximum size of a dynamic, scalable text field is relative to the other elements in the UI layout. A dynamic text field must not be so large that it displaces other UI layout elements, making them difficult to access.

Do recommendation illustrated by a green checkbox icon
Do
Text fields should adapt to the amount of text they contain and to user actions
Don't recommendation illustrated by a red X icon
Don't
Text fields should not be restricted in size when the windows layout permits scaling

Formatting

Anatomy and layout

Anatomy
A text field's labeled parts.
Anatomy of a text field

A text field can contain and be paired with the following elements:

1. Control label
2. View
3. Body (container)

1. Control label
Labels should be placed to the left of the text field. Labels can also be placed above the field when necessary. Labels should be simple and clear, relating to the nature of content.

2. View
The view of a text area is the space within the body where content is displayed. The view expands proportionately with the text area’s body until its size limit is reached, at which point it is used to display portions of the content inside.

3. Body (container)
The body of a dynamic, scalable text box spans the width of the window it occupies, maintaining a thin margin on either side.

Layout and scaling
A text field relative to its margins and padding
Outer margins and inner paddings of a text field.

When resizing a row with a text field horizontally, internal paddings and margins remain the same but the width of the body (container) scales to fit the new width.

A window that maintains the size of its padding and margins as it is scaled horizontally
Horizontal scaling a window with a text field, showing padding and margins maintaining their size

The body of a dynamic text box should also scale vertically to fit content, always maintaining the same lower margin between the lowest line of a text string and the edge of the content body.

A window that maintains the size of its padding and margins as it is scaled vertically
Vertical scaling a window with a text field, showing padding and margins maintaining their size
Icon of a letter I in a blue circle indicating this is a piece of informational content
Scrollbars and text fields
Consider using a scrollbar when a text field is vertically longer than nine lines.

Interaction states

Interaction states for text fields

Default
Text fields in the Default state are inactive but not disabled. Only a portion of the content entered may be visible. When empty, it will appear as a standard empty field. Text fields in the Default state will show any content entered as well as any controls generated to help navigate the content (such as Scrollbars).

Hover
When hovering over a text field’s 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 text 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).

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

Icon of a letter I in a blue circle indicating this is a piece of informational content
Disabled state opacity
In the IMGUI framework, disabled states have 40% opacity by default.

Color

Text field color variables
Color variables of a text field
1. text
--unity-colors-default-background
The default background color for controls
#A5A5A5
#282828
2. input_field-border
--unity-colors-highlight-background-hover
The background color for line items when the mouse pointer hovers over them
rgba(0, 0, 0, 0.0627451)
rgba(256, 256, 256, 0.0627451)
--unity-colors-highlight-background-hover-lighter
The background color for an item with a line specific background color when the mouse pointer hovers over them
#9A9A9A
#5F5F5F
--unity-colors-highlight-background-inactive
The background color for selected items or selected text when the control does not have focus
#AEAEAE
#4D4D4D
--unity-colors-highlight-text
The text color for selected items or selected text
#0032E6
#4C7EFF
3. input_field-background
--unity-colors-highlight-background
The background color for selected items or selected text
#3A72B0
#2C5D87

Code samples

UI Toolkit samples

Icon indicating this element is available in UI Builder

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

UI Builder text field icon