Implementation references

Scripting API and implementation references.

UI Toolkit
IMGUI

Overview

Default list view and a dark theme list view foldout featuring alternating row backgrounds and a vertical scroller
  • List view displays items as a flat list unlike tree view which displays items in a multi-tiered hierarchy
  • This control only creates visual elements for visible items while allowing the binding of many more items
  • As the user scrolls, visual elements in list view are recycled and re-bound to new data items

List view APIs

List view in UI Toolkit

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
ListView
Makes a flat list of items
List view in IMGUI

IMGUI

Not available in IMGUI framework
List views are currently not available in IMGUI framework, however you can still instantiate them with UI Toolkit framework.

Guidance

Choosing between foldout, list view and tree view

1. Tree View 2. List View 3. Foldout
  • Tree view is used for displaying items in a multi-tiered hierarchy, like a folder structure
  • List view is used for displaying items as a flat list
  • Foldout is used to expand / collapse a single level of mixed content, like Inspector controls

Using a foldout with list view

1. Default list view  2. List view with  foldout

Do not manually insert a foldout control inside list view. Instead use list view’s built-in option for adding a foldout.

Style

Row height
An annotated diagram of a foldout header and foldout contents
Tree and list views with 16 px row heights

List view requires all visual elements to have the same height so that it can calculate a sensible scroller size.

itemHeight property must be set for the list view to function.

Alternating row backgrounds

Use showAlternatingRowBackgrounds property to add alternating row background colors to the list view.

Show border

Use showBorder property to show a border around the list view.

Behavior

Scrolling content

List view contents are always displayed in a scroll view container to enable scrolling when the contents are larger than the viewport.

  • Vertical scrolling is enabled by default
  • Change horizontalScrollingEnabled property to True to display horizontal scrolling. (The default value is False)
Selecting list items

Selection state can be set to disable selections, have one selectable item, or have multiple selectable items by using selectionType property.

Reordering

List view items can be dragged to reorder their position by using reorderable property.

Formatting

Anatomy and layout

Anatomy
Anatomy of a list view and its key parts

A list view can contain and be paired with the following elements:

1. List view foldout
2. List view
3. List view row
4. Scrollbar

Interaction states

The various interactive states of a list view
Default

Default state of a list view row.

Hovered

When hovered, list view rows are highlighted.

Selected

When selected, list view rows are highlighted.

Focused

When focused, list view rows are highlighted in blue.

Disabled

Disabled list view items.

Color

Color variables used in scroll view
1. List view item backgrounds
--unity-colors-alternated_rows-background
The alternate background color for views with alternating row colors
#CACACA
#3F3F3F
--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
--unity-colors-highlight-background-inactive
The background color for selected items or selected text when the control does not have focus
#AEAEAE
#4D4D4D
2. List view item label
--unity-colors-default-text
The default text color
#090909
#D2D2D2
--unity-colors-default-text-hover
The default text color when the mouse pointer hovers over the text
#090909
#BDBDBD
--unity-colors-label-text-focus
The text color for a label when it has focus
#003C88
#81B4FF

Code samples

Code references

Scripting references for

IMGUI

IMGUI

Not available in IMGUI framework
List views are currently not available in IMGUI framework, however you can still instantiate them with UI Toolkit framework