Class ListView

A ListView is a vertically scrollable area that links to, and displays, a list of items.

Inheritance
Object
CallbackEventHandler
Focusable
VisualElement
BindableElement
ListView
Inherited Members
Namespace: UnityEngine.UIElements
Syntax
public class ListView : BindableElement, IEventHandler, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, IResolvedStyle, IBindable, ISerializationCallbackReceiver
Remarks

A ListView is a ScrollView with additional logic to display a list of vertically-arranged VisualElements. Each VisualElement in the list is bound to a corresponding element in a data-source list. The data-source list can contain elements of any type.\ \ The logic required to create VisualElements, and to bind them to or unbind them from the data source, varies depending on the intended result. It's up to you to implement logic that is appropriate to your use case. For the ListView to function correctly, you must supply at least the following:

The ListView creates VisualElements for the visible items, and supports binding many more. As the user scrolls, the ListView recycles VisualElements and re-binds them to new data items.

Examples
public class ListViewExampleWindow : EditorWindow
{
    [MenuItem("Window/ListViewExampleWindow")]
    public static void OpenDemoManual()
    {
        GetWindow<ListViewExampleWindow>().Show();
    }

    public void OnEnable()
    {
        // Create a list of data. In this case, numbers from 1 to 1000.
        const int itemCount = 1000;
        var items = new List<string>(itemCount);
        for (int i = 1; i <= itemCount; i++)
            items.Add(i.ToString());

        // The "makeItem" function is called when the
        // ListView needs more items to render.
        Func<VisualElement> makeItem = () => new Label();

        // As the user scrolls through the list, the ListView object
        // recycles elements created by the "makeItem" function,
        // and invoke the "bindItem" callback to associate
        // the element with the matching data item (specified as an index in the list).
        Action<VisualElement, int> bindItem = (e, i) => (e as Label).text = items[i];

        // Provide the list view with an explict height for every row
        // so it can calculate how many items to actually display
        const int itemHeight = 16;

        var listView = new ListView(items, itemHeight, makeItem, bindItem);

        listView.selectionType = SelectionType.Multiple;

        listView.onItemsChosen += objects => Debug.Log(objects);
        listView.onSelectionChange += objects => Debug.Log(objects);

        listView.style.flexGrow = 1.0f;

        rootVisualElement.Add(listView);
    }
}

Constructors

ListView()

Creates a ListView with all default properties. The , itemHeight, makeItem and bindItem properties must all be set for the ListView to function properly.

Declaration
public ListView()

ListView(IList, Int32, Func<VisualElement>, Action<VisualElement, Int32>)

Constructs a ListView, with all required properties provided.

Declaration
public ListView(IList itemsSource, int itemHeight, Func<VisualElement> makeItem, Action<VisualElement, int> bindItem)
Parameters
Type Name Description
IList itemsSource

The list of items to use as a data source.
Int32 itemHeight

The height of each item, in pixels.
Func<VisualElement> makeItem

The factory method to call to create a display item. The method should return a VisualElement that can be bound to a data item.
Action<VisualElement, Int32> bindItem

The method to call to bind a data item to a display item. The method receives as parameters the display item to bind, and the index of the data item to bind it to.

Fields

borderUssClassName

The USS class name for ListView elements with a border.

Declaration
public static readonly string borderUssClassName
Field Value
Type Description
String
Remarks

Unity adds this USS class to an instance of the ListView element if the instance's showBorder property is set to true. Any styling applied to this class affects every such ListView located beside, or below the stylesheet in the visual tree.

dragHoverBarUssClassName

The USS class name of the drag hover bar.

Declaration
public static readonly string dragHoverBarUssClassName
Field Value
Type Description
String
Remarks

Unity adds this USS class to the bar that appears when an item element is dragged. The reorderable property must be true in order for items to be dragged. Any styling applied to this class affects every ListView located beside, or below the stylesheet in the visual tree.

itemAlternativeBackgroundUssClassName

The USS class name for odd rows in the ListView.

Declaration
public static readonly string itemAlternativeBackgroundUssClassName
Field Value
Type Description
String
Remarks

Unity adds this USS class to every odd-numbered item in the ListView when the property is set to ContentOnly or All. When the showAlternatingRowBackground property is set to either of those values, odd-numbered items are displayed with a different background color than even-numbered items. This USS class is used to differentiate odd-numbered items from even-numbered items. When the showAlternatingRowBackground property is set to None, the USS class is not added, and any styling or behavior that relies on it's invalidated.

itemDragHoverUssClassName

The USS class name applied to an item element on drag hover.

Declaration
public static readonly string itemDragHoverUssClassName
Field Value
Type Description
String
Remarks

Unity adds this USS class to the list element that is dragged. The reorderable property must be set to true for items to be draggable. Any styling applied to this class affects every ListView item located beside, or below the stylesheet in the visual tree.

itemSelectedVariantUssClassName

The USS class name of selected item elements in the ListView.

Declaration
public static readonly string itemSelectedVariantUssClassName
Field Value
Type Description
String
Remarks

Unity adds this USS class to every selected element in the ListView. The selectionType property decides if zero, one, or more elements can be selected. Any styling applied to this class affects every ListView item located beside, or below the stylesheet in the visual tree.

itemUssClassName

The USS class name of item elements in ListView elements.

Declaration
public static readonly string itemUssClassName
Field Value
Type Description
String
Remarks

Unity adds this USS class to every item element the ListView contains. Any styling applied to this class affects every item element located beside, or below the stylesheet in the visual tree.

ussClassName

The USS class name for ListView elements.

Declaration
public static readonly string ussClassName
Field Value
Type Description
String
Remarks

Unity adds this USS class to every instance of the ListView element. Any styling applied to this class affects every ListView located beside, or below the stylesheet in the visual tree.

Properties

bindItem

Callback for binding a data item to the visual element.

Declaration
public Action<VisualElement, int> bindItem { get; set; }
Property Value
Type Description
Action<VisualElement, Int32>
Remarks

The method called by this callback receives the VisualElement to bind, and the index of the element to bind it to.

contentContainer

Returns the content container for the ListView. Because the ListView control automatically manages its content, this always returns null.

Declaration
public override VisualElement contentContainer { get; }
Property Value
Type Description
VisualElement
Overrides

horizontalScrollingEnabled

This property controls whether the ListView shows a horizontal scroll bar when its content does not fit in the visible area.

Declaration
public bool horizontalScrollingEnabled { get; set; }
Property Value
Type Description
Boolean
Remarks

The default value is false. Set this property to true to display a horizontal scroll bar.

itemHeight

The height of a single item in the list, in pixels.

Declaration
public int itemHeight { get; set; }
Property Value
Type Description
Int32
Remarks

ListView requires that all visual elements have the same height so that it can calculate the scroller size.

itemsSource

The data source for list items.

Declaration
public IList itemsSource { get; set; }
Property Value
Type Description
IList
Remarks

This list contains the items that the ListView displays.

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

makeItem

Callback for constructing the VisualElement that is the template for each recycled and re-bound element in the list.

Declaration
public Func<VisualElement> makeItem { get; set; }
Property Value
Type Description
Func<VisualElement>
Remarks

This callback needs to call a function that constructs a blank VisualElement that is bound to an element from the list.

The ListView automatically creates enough elements to fill the visible area, and adds more if the area is expanded. As the user scrolls, the ListView cycles elements in and out as they appear or disappear.

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

reorderable

Gets or sets a value that indicates whether the user can drag list items to reorder them.

Declaration
public bool reorderable { get; set; }
Property Value
Type Description
Boolean
Remarks

The default values is false. Set this value to true to allow the user to drag and drop the items in the list. The ListView provides a default controller to allow standard behavior. It also automatically handles reordering the items in the data source.

resolvedItemHeight

The computed pixel-aligned height for the list elements.

Declaration
public float resolvedItemHeight { get; }
Property Value
Type Description
Single
Remarks

This value changes depending on the current panel's DPI scaling.

See Also

selectedIndex

Returns or sets the selected item's index in the data source. If multiple items are selected, returns the first selected item's index. If multiple items are provided, sets them all as selected.

Declaration
public int selectedIndex { get; set; }
Property Value
Type Description
Int32

selectedIndices

Returns the indices of selected items in the data source. Always returns an enumerable, even if no item is selected, or a single item is selected.

Declaration
public IEnumerable<int> selectedIndices { get; }
Property Value
Type Description
IEnumerable<Int32>

selectedItem

Returns the selected item from the data source. If multiple items are selected, returns the first selected item.

Declaration
public object selectedItem { get; }
Property Value
Type Description
Object

selectedItems

Returns the selected items from the data source. Always returns an enumerable, even if no item is selected, or a single item is selected.

Declaration
public IEnumerable<object> selectedItems { get; }
Property Value
Type Description
IEnumerable<Object>

selectionType

Controls the selection type with values of SelectionType enum.

Declaration
public SelectionType selectionType { get; set; }
Property Value
Type Description
SelectionType
Remarks

The default value is Single. When you set the ListView to disable selections, any current selection is cleared.

showAlternatingRowBackgrounds

This property controls whether the background colors of ListView rows alternate. Takes a value from the AlternatingRowBackground enum.

Declaration
public AlternatingRowBackground showAlternatingRowBackgrounds { get; set; }
Property Value
Type Description
AlternatingRowBackground
Remarks

The default value is None.

showBorder

Enable this property to display a border around the ListView.

Declaration
public bool showBorder { get; set; }
Property Value
Type Description
Boolean
Remarks

If set to true, a border appears around the ScrollView that the ListView uses internally.

showBoundCollectionSize

This property controls whether the list view displays the collection size (number of items).

Declaration
public bool showBoundCollectionSize { get; set; }
Property Value
Type Description
Boolean
Remarks

The default values if true. When this property is set to false, Unity displays the collection size as the first item in the list, but does not make it an actual list item that is part of the list index. If you query for list index 0, Unity returns the first real list item, and not the collection size. This property is usually used to debug a ListView, because it indicates whether the data source is linked correctly. In production, the collection size is rarely displayed as a line item in a ListView.

See Also
Bind(VisualElement, SerializedObject)

unbindItem

Callback for unbinding a data item from the VisualElement.

Declaration
public Action<VisualElement, int> unbindItem { get; set; }
Property Value
Type Description
Action<VisualElement, Int32>
Remarks

The method called by this callback receives the VisualElement to unbind, and the index of the element to unbind it from.

Methods

AddToSelection(Int32)

Adds an item to the collection of selected items.

Declaration
public void AddToSelection(int index)
Parameters
Type Name Description
Int32 index

Item index.

ClearSelection()

Deselects any selected items.

Declaration
public void ClearSelection()

ExecuteDefaultAction(EventBase)

Declaration
protected override void ExecuteDefaultAction(EventBase evt)
Parameters
Type Name Description
EventBase evt
Overrides

OnKeyDown(KeyDownEvent)

Declaration
public void OnKeyDown(KeyDownEvent evt)
Parameters
Type Name Description
KeyDownEvent evt

Refresh()

Clears the ListView, recreates all visible visual elements, and rebinds all items.

Declaration
public void Refresh()
Remarks

Call this method whenever the data source changes.

RemoveFromSelection(Int32)

Removes an item from the collection of selected items.

Declaration
public void RemoveFromSelection(int index)
Parameters
Type Name Description
Int32 index

The item index.

ScrollTo(VisualElement)

Scrolls to a specific VisualElement.

Declaration
public void ScrollTo(VisualElement visualElement)
Parameters
Type Name Description
VisualElement visualElement

The element to scroll to.

ScrollToItem(Int32)

Scrolls to a specific item index and makes it visible.

Declaration
public void ScrollToItem(int index)
Parameters
Type Name Description
Int32 index

Item index to scroll to. Specify -1 to make the last item visible.

SetSelection(IEnumerable<Int32>)

Sets a collection of selected items.

Declaration
public void SetSelection(IEnumerable<int> indices)
Parameters
Type Name Description
IEnumerable<Int32> indices

The collection of the indices of the items to be selected.

SetSelection(Int32)

Sets the currently selected item.

Declaration
public void SetSelection(int index)
Parameters
Type Name Description
Int32 index

The item index.

SetSelectionWithoutNotify(IEnumerable<Int32>)

Sets a collection of selected items without triggering a selection change callback.

Declaration
public void SetSelectionWithoutNotify(IEnumerable<int> indices)
Parameters
Type Name Description
IEnumerable<Int32> indices

The collection of items to be selected.

Events

onItemChosen

Callback triggered that's activated when a user double-clicks an item. This is different from selecting the item.

Declaration
public event Action<object> onItemChosen
Event Type
Type Description
Action<Object>

onItemsChosen

Callback triggered when the user acts on a selection of one or more items. For example, by double-clicking or pressing Enter.

Declaration
public event Action<IEnumerable<object>> onItemsChosen
Event Type
Type Description
Action<IEnumerable<Object>>
Remarks

This callback receives an enumerable that contains the item or items chosen.

onSelectionChange

Callback triggered when the selection changes.

Declaration
public event Action<IEnumerable<object>> onSelectionChange
Event Type
Type Description
Action<IEnumerable<Object>>
Remarks

This callback receives an enumerable that contains the item or items selected.

onSelectionChanged

Callback triggered when the selection changes.

Declaration
public event Action<List<object>> onSelectionChanged
Event Type
Type Description
Action<List<Object>>

Extension Methods