Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Numeric field · UX essentials

Key guidance on how to effectively use numeric fields.

Sliders, numeric fields, and toggles can be interacted with via their label
Blue plus sign icon indicating that clicking on this will expand this content
When to disable controls or hide them altogether
Blue plus sign icon indicating that clicking on this will expand this content

Overview

Numeric fields in light and dark themes
Single and multi numeric fields

Unity Editor contains multiple field types for;

  • A numeric field is a basic control that enables the user to input numbers
  • They typically appear in forms like the Inspector or Settings windows
  • Numeric inputs enable calculations or precise interface settings

Numeric field types

Single and multi numeric fields shown in dark theme
Single and multi numeric fields

Int vs float: Variations of number data types

  • Numerical data is categorized as either integers or floats
  • Integers are numbers without a decimal point and are expressed as Int in the codebase
  • Floats are floating-point numbers with decimals, which allows for more precision than integers

Single fields

A single numeric field in dark theme

A single numeric field

When to use

Use Single Fields for inputing a single data point in numeric fields.

UI Builder toolbar iconUI Builder icon for float fieldUI Builder icon for integer fieldUI Builder icon for long field
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}
APIs in UI Toolkit
DoubleField
Makes a numeric field for entering doubles
FloatField
Makes a numeric field for entering a float
IntegerField
Makes a numeric field for entering an integer
LongField
Makes a numeric field for entering long integers
APIs in IMGUI
EditorGUI.DoubleField
Makes a numeric field for entering doubles
EditorGUI.FloatField
Makes a numeric field for entering a float
EditorGUI.IntField
Makes a numeric field for entering an integer
EditorGUI.LongField
Makes a numeric field for entering long integers

Multi fields

A multi numeric field in dark theme

A multi numeric field

When to use

Use Multi Fields for inputting multiple data points in numeric fields.

UI Builder icon for bounds fieldUI Builder icon for bounds, intUI Builder icon for two vectors fieldsUI Builder icon for two vector fields, intUI Builder icon for three vectors fieldsUI Builder icon for two vectors fields, intUI Builder icon for four vectors fieldsUI Builder icon for rect field, normalUI Builder icon for rect field, int
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}
APIs in UI Toolkit
BoundsField
A Bounds numeric field
BoundsIntField
A BoundsInt numeric field
Vector2Field
A Vector2 numeric field
Vector2IntField
A Vector2Int numeric field
Vector3Field
A Vector3 numeric field
Vector3IntField
A Vector3Int numeric field
Vector4Field
A Vector4 numeric field
RectField
A Rect numeric field
RectIntField
A RectInt numeric field
APIs in IMGUI
EditorGUI.BoundsField
A Bounds numeric field
EditorGUI.BoundsIntField
A BoundsInt numeric field
EditorGUI.Vector2Field
A Vector2 numeric field
EditorGUI.Vector2IntField
A Vector2Int numeric field
EditorGUI.Vector3Field
A Vector3 numeric field
EditorGUI.Vector3IntField
A Vector3Int numeric field
EditorGUI.Vector4Field
A Vector4 numeric field
EditorGUI.RectField
A Rect numeric field
EditorGUI.RectIntField
A RectInt numeric field

Guidance

When to use

  • Use a numeric field when an input field is needed that allows users to enter numbers for calculations or for precise settings
  • If a whole number is needed, use an Integer (Int) field; if a decimal number is needed, use a Float field

When to pair numeric fields with sliders

Numeric fields work best for making small, incremental changes that require precise input. When large, imprecise value changes are expected, pair Numeric Fields with sliders.

Style

Default value

Ensure that a default value is always shown in the field where possible.

Numeric field positioning
A basic slider with a numeric field on the left and a  min/max slider with a numeric field on the right
A basic slider and a min/max slider with corresponding numeric fields

Single numeric fields:
When paired with a basic slider, numeric fields are positioned to the right of the Slider.

Min/max numeric fields:
When paired with a min/max slider, numeric fields are positioned on both sides of the Slider, to represent the minimum and maximum values.

Behavior

Adjusting with label

Numeric fields are an adjustment-based control element, where the numerical value in the field determines its value.

  • Numeric field value can be adjusted through its label by hovering and dragging the cursor left or right. The cursor switches its glyph when positioned over the label to communicate this ability
Invalid entry

When a value that is invalid for the property is entered, input fields show last valid value.

  • Input fields revert back to the last valid value when unfocused.
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.
DelayedIntField

EditorGUI.Delayed
IntField

docs.unity3d.com

Arrow icon indicating link goes to an external source
Icon displaying the Unity logo
EditorGUI.
DelayedFloatField

EditorGUI.Delayed
FloatField

docs.unity3d.com

Arrow icon indicating link goes to an external source
Icon displaying the Unity logo
EditorGUI.
DelayedDoubleField

EditorGUI.Delayed
DoubleField

docs.unity3d.com

Arrow icon indicating link goes to an external source
Integer, float and double fields
  • Avoid hidden or implicit behavior when a number field has not yet changed from its original value. If a change in value produces a change in behavior, consider placing the control behind an explicit decision that the user must make (such as a toggle or a popup), so that the user is clear about what should happen.
  • Disallow entry of any value that is invalid for the property
  • If the value is bounded on both ends, use a slider
  • Pressing enter/return confirms and finishes entry of the text
  • Pressing escape cancels the current entry, and reverts the field to the value it was before editing began
  • For forcing value entry, use MonoBehavior.OnValidate callback
Icon displaying the Unity logo
EditorGUI.IntField

Scripting API for text field for entering integers.

docs.unity3d.com

Arrow icon indicating link goes to an external source
Icon displaying the Unity logo
EditorGUI.FloatField

Scripting API for text field for entering floats.

docs.unity3d.com

Arrow icon indicating link goes to an external source
Icon displaying the Unity logo
EditorGUI.DoubleField

Scripting API for text field for entering doubles.

docs.unity3d.com

Arrow icon indicating link goes to an external source

Formatting

Anatomy and layout

Anatomy
An annotated image of a single numeric field and its parts in dark theme
A single numeric field and its parts

A numeric 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 numeric field, such as X Y Z coordinate labels in Vector3 fields. Labels should be simple and clear, relating to the nature of content.

2. View

The view of a numeric field is the space within the body (container) where content is displayed.

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
A single numeric field showing a smaller field on the left and on the right a field scaling horizontally larger
A single numeric field scaling horizontally

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

Interaction states

A numeric field in light and dark themes showing four interactive states
Numeric field in its interactive states
Default

Default state of a Numeric Field.

Hover

When hovering over a numeric 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 numeric 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 numeric field that is disabled will indicate so by having its body “greyed out” and will not accept inputs or react to hovering.

Color

An annotated numeric field in light and dark themes with labels for text color, input field border color and input field background color.
1. text 2. input_field-border 3. input_field-background
1. text
--unity-colors-button-border-pressed
The border color for a button control when it is pressed
#707070
#0D0D0D
2. input_field-border
--unity-colors-helpbox-text
The text color for a helpbox control
#161616
#BDBDBD
--unity-colors-highlight-background
The background color for selected items or selected text
#3A72B0
#2C5D87
--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
3. input_field-background
--unity-colors-helpbox-border
The border color for a helpbox control
#A9A9A9
#232323

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 icon for double fieldUI Builder icon for float fieldUI Builder icon for integer fieldUI Builder icon for long field
UI Builder icon for bounds fieldUI Builder icon for bounds, intUI Builder icon for two vectors fieldsUI Builder icon for two vector fields, intUI Builder icon for three vectors fieldsUI Builder icon for two vectors fields, intUI Builder icon for four vectors fieldsUI Builder icon for rect field, normalUI Builder icon for rect field, int