UXML element MultiColumnListView

A MultiColumnListView is a UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary control commonly used to display tabular or grid-like data with multiple columns. It allows you to present data in a structured format, where each row represents an item or entry, and each column represents a specific attribute or property of that item.

Create a MultiColumnListView

You can create a MultiColumnListView with UXML and C#. The following C# example creates a MultiColumnListView with two columns:

var multiColumnListView = new MultiColumnListView();
multiColumnListView.columns.Add(new Column { title = "Name", width = 20 });
multiColumnListView.columns.Add(new Column { title = "Power", width = 80 });

Refresh the collection view

To refresh the collection view, in general, call the RefreshItems or RefreshItem method. However, in the following cases, call Rebuild instead to refresh the collection view:

• You change the type of the data source, such as changing from a List<float> to a List<Vector3>.
• You make changes to makeItem or destroyItem.

Note: If you call Rebuild, the collection view is completely rebuilt, which can be expensive. If you call RefreshItems or RefreshItem, the collection view is only refreshed, which is less expensive.

Bind the MultiColumnListView to data

You can bind the MultiColumnListView to a data source, and automatically populate the rows and columns based on the provided data.

For example, if you have a ScriptableObject with the following structure:

[Serializable]
public class Move
{
    public string name;
    public int power;
}

[Serializable]
public class Monster
{
    public string name;
    public List<Move> moves;
}

public class MonstersTeam : ScriptableObject
{
    public List<Monster> monstersList;
}

You can bind a MultiColumnListView to the ScriptableObject with the following code:

var multiColumnListView = new MultiColumnListView
{
    bindingPath = "monstersList",
    showBoundCollectionSize = false,
    virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight
};
multiColumnListView.columns.Add(new Column { bindingPath = "name", title = "Name", stretchable = true });
multiColumnListView.columns.Add(new Column { bindingPath = "moves", title = "Moves", stretchable = true });

var so = new SerializedObject(monstersTeam);
multiColumnListView.Bind(so);

This outputs the following view:

To make the nested list a MultiColumnListView, change makeCell in the Moves column:

var multiColumnListView = new MultiColumnListView
{
    bindingPath = "monstersList",
    showBoundCollectionSize = false,
    virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight
};
multiColumnListView.columns.Add(new Column { bindingPath = "name", title = "Name", stretchable = true });
multiColumnListView.columns.Add(new Column { bindingPath = "moves", title = "Moves", stretchable = true,
    makeCell = () =>
    {
        var movesMultiColumnListView = new MultiColumnListView
        {
            showBoundCollectionSize = false,
            virtualizationMethod = CollectionVirtualizationMethod.DynamicHeight,
        };
        movesMultiColumnListView.columns.Add(new Column { bindingPath = "name", title = "Name", stretchable = true });
        movesMultiColumnListView.columns.Add(new Column { bindingPath = "power", title = "Power", stretchable = true });
        return movesMultiColumnListView;
    }}
); 

var so = new SerializedObject(monstersTeam);
multiColumnListView.Bind(so);

This outputs the following view:

Sort the MultiColumnListView

You can enable sorting for MultiColumnListView using a default algorithm, or implementing custom algorithm if the default sorting operation isn’t fast enough to meet your needs.

Once the sorting is enabled, to sort by a single column, click the column headers. To sort multiple columns, hold down the Ctrl key (macOS: Cmd) and click. To disable sorting, hold down the Shift key and click.

Default sorting

To enable sorting using the default algorithm, set the sortingMode attribute to ColumnSortingMode.Default, and implement the Column.comparison to compare two items by their index in the source.

For an example, refer to a MultiColumnListView default sorting example.

Custom sorting

To implement custom sorting, set the sortingMode attribute to ColumnSortingMode.Custom, and implement the columnSortingChanged callback. In the callback, use sortColumns to reorder your list accordingly and trigger a RefreshItems() once the items’ source has been updated.

The sortColumns attribute is the current state of sorted columns: it lists the columns in the order in which they’re sorted. If you sort by column 1, then column 2, then column 3, the sortedColumns list is [1, 2, 3]. If you sort by column 3, then column 2, then column 1, the sortedColumns list is [3, 2, 1].

Implement drag-and-drop operations for MultiColumnListView

Drag-and-drop is a common feature in UI design. To implement the drag-and-drop operations, override the following methods:

• To enable dragging items, override canStartDrag.
• To set which items are dragged, override setupDragAndDrop.
• To get item status changes, override dragAndDropUpdate. You can perform certain actions based on the drag position or other conditions.
• To control the drag-and-drop behavior, override handleDrop.

During the drag-and-drop operation, you can enable the reordering of items by dragging. To enable, set the reorderable attribute to true in UI Builder, UXML, and C#.

Refer to Create a drag-and-drop list and tree views between windows for an example. You can also use the Matching Selectors section in the Inspector or the UI Toolkit Debugger to see which USS selectors affect the components of the VisualElement at every level of its hierarchy.

Examples

• Create list and tree views: Use ListView, TreeView, MultiColumnListView, and MultiColumnTreeView to create list and tree views.
• Create a drag-and-drop list and tree views between windows: Use ListView, TreeView, and MultiColumnListView to create a drag-and-drop UI between windows.

C# base class and namespace

C# class: MultiColumnListView
Namespace: UnityEngine.UIElements
Base class: BaseListView

Member UXML attributes

This element has the following member attributes:

Inherited UXML attributes

This element inherits the following attributes from its base class:

This element also inherits the following attributes from VisualElement:

USS classes

The following table lists all the C# public property names and their related USS selector.

You can also use the Matching Selectors section in the Inspector or the UI Toolkit Debugger to see which USS selectors affect the components of the VisualElement at every level of its hierarchy.

Additional resources

• UXML element ListView
• UXML element TreeView
• UXML element ScrollView
• UXML element MultiColumnTreeView