Implementation references
Scripting API and implementation references.
UI Toolkit
IMGUI
Overview
- 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: 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.
When to use
Used for single-line text inputs.
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.
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
EditorGUI.Delayed
TextField
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.
Formatting
Anatomy and layout
Anatomy
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
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.
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.
Interaction states
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.
Color
Text field color variables
1. text
2. input_field-border
3. input_field-background
Code samples
UI Toolkit samples
Go to Window > UI Toolkit > Samples, to view code samples in C# / USS / UXML.
Scripting references for
UI Toolkit
Unity - Scripting API:
TextField
Scripting references for
IMGUI
Unity - Scripting API:
EditorGUILayout.TextField
Unity - Scripting API:
EditorGUILayout.TextArea
Resources and related
