Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Slider · UX essentials

Key guidance on how to effectively use slider controls.

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

Resources and API documentation

Overview

1. Basic slider 2. Min-max slider

Unity Editor contains 2 type of sliders (checkboxes);

  • Sliders are draggable control elements that allow the user to manually set a value from a groove representing an allowable range
  • A slider enables users to change values by moving the handle(s) toward either end of its length
  • Sliders are often accompanied by a Numeric Field, which displays a value and acts as an alternate input that gives greater specificity than a draggable control

Slider variations

Basic slider

A basic slider
When to use

Used for single-value inputs: These sliders appear in circumstances where a user needs to assign a value within a range, with the position of the handle directly reflecting the assigned value.

Slider iconSlider int 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}
APIs in

UI Toolkit

Slider
Makes a slider containing floating point values
SliderInt
Makes a slider containing integer discrete values
APIs in

IMGUI

EditorGUI.Slider
Makes a slider containing floating point values
EditorGUI.IntSlider
Makes a slider containing integer discrete values
Min-max slider
A min max slider
When to use

Allows the user to specify a range between a minimum and a maximum.

A min max slider 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

MinMaxSlider
A min-max slider containing a representation of a range
API in

IMGUI

EditorGUI.MinMaxSlider
A min-max slider containing a representation of a range

Guidance

When to use

  • Sliders are used to choose a value between a finite range of minimum and maximum values
  • Min-max sliders are used to alllow users to specify a range between a minimum and a maximum
  • Sliders often appear in interfaces where an absolute value is unclear or where slight alterations to a value is desired. In these cases sliders allow for experimentation within a range of values while providing the ensuing visual changes immediately
The field of view slider on a main camera object zooms in and out

How to use

  • Slider inputs should be immediately responsive, and visualized in the Scene View if possible
  • Sliders should control an individual variable, not multiple variables
  • Consider adding a numeric field when a precise value is required. Precise values are more difficult to achieve with slider handles
The field of view slider on a main camera object zooms in and out
  • Sliders should only be used for linear values, such as those which can be represented by numerals. They should not be used for non-linear values like position or rotation which are better served by in-view tools and input fields
  • Avoid Sliders on items which may have redundant or more specialized controls, for example on Transforms
Do recommendation illustrated by a green checkbox icon
Do
Sliders should relate to individual variables.
 
A discouraged usage of a variable that uses multiple sliders
Don't recommendation illustrated by a red X icon
Don't
Avoid sliders on items with multiple or specialized controls, for example when using the transform function

Style

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.

Text label

A slider’s label should clearly indicate the nature of the value being set. The label should always appear to the left of the component.

Slider handle
Icon of a letter I in a blue circle indicating this is a piece of informational content
Alternate name
A slider handle is alternately referred to as a “slider thumb” in some documentation and API names.
A basic slider with a text label on the left and a numeric field on the right.
A basic slider with a text label on its left and a numeric field to its right

Handles appear as a circular control above the Slider Groove. The handle’s position represents the current value for the Slider; the farther to the right of the Groove, the higher the value. A Slider’s Handle cannot pass beyond the edges of its Groove, which is bookended with the minimum and maximum values at either end.

Movement of the slider’s handle changes the value. On a typical horizontal slider, both the left and right ends of the slider represent the two extreme values allowed by the control.

Slider groove
Icon of a letter I in a blue circle indicating this is a piece of informational content
Alternate name
A slider groove is alternately referred to as a “slider track” in some documentation and API names.
  • Slider Groove should be laid out horizontally; the far left of the slider represents the lowest available value while the far right represents the highest available value
  • The length of a slider should be consistent with other sliders within the same interface; while the proportionate change in value may differ the Groove should occupy the same amount of space
  • In situations where the range allows and/or requires a level of accuracy that becomes difficult to control with the handle alone a Numeric Field can be placed to the right or left of the Slider, displaying the current value and allowing users to adjust it directly through numeric inputs
Mouse cursor

The cursor’s glyph will adapt depending on which portion of the slider it’s positioned above; when the cursor hovers over the slider’s label it automatically converts to a “scrub” glyph, while it will show a text cursor if positioned above an attached numeric field.

Cursor changing format while moving
Cursor changes from scrub glyph to text cursor when hovering over a Numeric Field

Adjusting sliders

Sliders are an adjustment-based control element, where the position of the control dictates the current value assigned to its subject.

Mouse events: Slider label and handle
  • Dragging a sliders handle to the left should always result in a decrease in value while dragging to the right should always result in an increase
  • A slider can have its value reset by clicking on or scrubbing along the track
  • If a user clicks on the Groove (not on the Handle) the value will be set to the click’s location, with the Handle automatically repositioning underneath the cursor to reflect the new input. If the user clicks and drags along the Groove the Handle will reposition below the cursor
  • The Slider’s value can also be adjusted through its label.: If a user clicks and holds while hovering over the slider’s label they can change the value by dragging the cursor left or right. The cursor switches its glyph when positioned over the label to communicate this ability
Keyboarding
  • When focused, the right arrow key should increase the Slider's value and the left arrow key should decrease it
  • Pressing and holding an arrow key will cause the value to continuously increase until it has reached the maximum or minimum allowable

Formatting

Anatomy and layout

Anatomy
The labeled elements of a slider
Anatomy of a slider featuring its four most common elements

A slider can contain the following elements:

1. Label
2. Slider handle (also called slider thumb)
3. Slider groove (also called slider track)
4. Numeric field

Layout
The labeled layout of a slider
Four common aspects of a slider’s layout
  • Text label aligns with left edge of its window
  • Sliders expand left when window is resized
  • Sliders retain their right margin when window is resized
  • Numerical fields aligns with right edge of its window

Interaction states

Light and dark themed sliders demonstrating interactive states
Light and dark themed sliders demonstrating interactive states
Default

A slider is still active when in its default state; because a Slider represents a value it can be considered active unless disabled and will always show the current value assigned (even if interactions with the component are not permitted).

Hover
  • The hover state for sliders varies based on which portion of the element the cursor is above
  • Hovering over the label and dragging right and left will adjust the slider
  • Hovering over a slider handle will cause the control element to return or show hover state highlight
  • Hovering over the label will cause the cursor to change to a “scrub” glyph
  • Hovering over an attached numeric field will cause the field to switch to a text cursor
  • Hovering over the Groove does not provoke any changes
Focused

When in the focused state the label, control, and attached field will all be highlighted. Pressing the Tab key moves the focus state to the next label/property, which is typically down. The arrow keys can be used to adjust the value left and right (to decrease and increase respectively).

Disabled

A disabled slider will be unresponsive to direct user actions but may still display the value associated with the Slider and, on occasion, be manipulated by other means (in code, or as a result of a scene progressing. Regardless of whether or not the Slider control changes position the Slider is considered to be in a “Disabled” state when it can not directly receive user input.

Color

Slider and min-max slider color variables
A slider in light and dark themes highlighting the fill color for a slider’s thumb and the background color for a slider’s groove
Light and dark themed slider demonstrating fill color and background color
1. slider-thumb
--unity-colors-scrollbar_button-background-hover
The background color for a scrollbar's scroll buttons when the mouse pointer hovers over them
#A7A7A7
#494949
--unity-colors-scrollbar_groove-background
The background color for a scrollbar's groove (background)
rgba(0, 0, 0, 0.05098039)
rgba(0, 0, 0, 0.05098039)
--unity-colors-scrollbar_groove-border
The border color for a scrollbar's groove
rgba(0, 0, 0, 0.1019608)
rgba(0, 0, 0, 0.1019608)
--unity-colors-scrollbar_thumb-background
The background color for a scrollbar's thumb/handle
#9A9A9A
#5F5F5F
--unity-colors-scrollbar_thumb-background-hover
The background color for a scrollbar's thumb/handle when the mouse pointer hovers over it
#8E8E8E
#686868
2. slider-groove
--unity-colors-progress-background
#606060
#303030
--unity-colors-scrollbar_button-background
The background color for a scrollbar's scroll buttons
rgba(0, 0, 0, 0.05098039)
rgba(0, 0, 0, 0.05098039)
3. slider-halo
--unity-colors-scrollbar_thumb-border
The border color for a scrollbar's thumb/handle
#B9B9B9
#323232

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.

Slider iconSlider, int, iconicon for min-max slider