List

List is a high-performance, virtualized container for rendering large datasets with built-in grouping, sorting, and visual formatting. It only renders visible items in the viewport, making it ideal for displaying thousands of records while maintaining smooth scrolling performance.

Key features:

• Virtualization: Renders only visible items for optimal performance with large datasets
• Advanced grouping: Group data by any field with customizable headers and footers
• Built-in sorting: Sort by any data field in ascending or descending order
• Visual formatting: Pre-styled list appearance with borders, spacing, and layout
• Pagination support: Handle large datasets with built-in pagination controls
• Empty state handling: Customizable templates for when no data is available

List vs Items: Use List for complex data presentation requiring performance optimization, grouping, sorting, or visual formatting. Use Items for simple data iteration without layout requirements.

In the following examples all use the same list of data which looks like so:

The data is provided as JSON.

Context variables available during execution:

• $group: Group information when using groupBy (available in group templates)
• $isFirst: Boolean indicating if this is the first item
• $isLast: Boolean indicating if this is the last item
• $isSelected: Boolean indicating if this item is currently selected
• $item: Current data item being rendered
• $itemIndex: Zero-based index of current item

Use children as Content Template

The itemTemplate property can be replaced by setting the item template component directly as the List's child. In the following example, the two List are functionally the same:

<App>
  <!-- This is the same -->
  <List>
    <property name="itemTemplate">
      <Text>Template</Text>
    </property>
  </List>
  <!-- As this -->
  <List>
    <Text>Template</Text>
  </List>
</App>

Behaviors

This component supports the following behaviors:

Properties

availableGroups

This property is an array of group names that the List will display. If not set, all groups in the data are displayed.

<App>
  <List
    data="{[...]}"
    groupBy="category"
    availableGroups="{['fruits', 'vegetables']}">
    <property name="groupHeaderTemplate">
      <Stack>
        <Text variant="subtitle" value="{$group.key}" />
      </Stack>
    </property>  
  </List>
</App>

borderCollapse

default: true

Collapse items borders

Note how the List on the right has different borders:

<App>
  <HStack>
    <List 
      data="{[...]}"
      groupBy="category" 
      borderCollapse="false" 
      width="$space-64"
    >
      <property name="groupHeaderTemplate">
        <Stack>
          <Text variant="subtitle" value="{$group.key}" />
        </Stack>
      </property>
    </List>
    <List 
      data="{[...]}" 
      groupBy="category" 
      borderCollapse="true" 
      width="$space-64"
    >
      <property name="groupHeaderTemplate">
        <Stack>
          <Text variant="subtitle" value="{$group.key}" />
        </Stack>
      </property>
    </List>
  </HStack>
</App>

data

The component receives data via this property. The data property is a list of items that the List can display.

Note how the List infers the given data and provides a simple layout for it. To tweak what data and how it is displayed, see the itemTemplate section.

<App>
  <List data='{[...]}' />
</App>

You can also provide the List with data directly from an API via this property.

In the example below, the List also uses the itemTemplate property to access the data attributes as well. See the itemTemplate section.

defaultGroups

This property adds an optional list of default groups for the List and displays the group headers in the specified order. If the data contains group headers not in this list, those headers are also displayed (after the ones in this list); however, their order is not deterministic.

For the defaultGroups property to work, the data must be sectioned using the groupBy property, and either a groupHeaderTemplate or a groupFooterTemplate needs to be provided.

<App>
  <List
    data='{[...]}'
    defaultGroups="{['dairy', 'meat', 'vegetables']}"
    groupBy="category" >
    <property name="groupHeaderTemplate">
      <VStack>
        <Text variant="subtitle" value="{$group.key}" />
      </VStack>
    </property>
  </List>
</App>

emptyListTemplate

This property defines the template to display when the list is empty.

<App>
  <List>
    <property name="emptyListTemplate">
      <VStack horizontalAlignment="center">
        <Text variant="strong" value="Empty..." />
      </VStack>
    </property>
  </List>
</App>

<App>
  <List>
    <property name="emptyListTemplate">
      <VStack horizontalAlignment="center">
        <Text variant="strong" value="Empty..." />
      </VStack>
    </property>
  </List>
</App>

enableMultiRowSelection

default: true

This boolean property indicates whether you can select multiple rows in the list. This property only has an effect when the rowsSelectable property is set. Setting it to false limits selection to a single row.

<App>
  <List data='{[...]}' rowsSelectable="true" enableMultiRowSelection="false">
    <Text>{$item.name}</Text>
  </List>
</App>

fixedItemSize

default: false

When set to true, the list will measure the height of the first item and use that as a fixed size hint for all items. This improves scroll performance when all items have the same height. If items have varying heights, leave this as false.

groupBy

This property sets which data item property is used to group the list items. Accepts a field name string or a function that receives an item and returns the group key. If not set, no grouping is done.

For the groupBy property to work, either a groupHeaderTemplate or a groupFooterTemplate needs to be provided.

groupBy accepts either a string (the name of the item field to group by) or a function that receives each list item and returns the grouping key.

String usage — group by a field name directly:

<App>
  <List
    data='{[...]}'
    groupBy="category">
    <property name="groupHeaderTemplate">
      <VStack>
        <Text variant="subtitle" value="{$group.key}" />
      </VStack>
    </property>
  </List>
</App>

Function usage — compute the grouping key from each item:

<App>
  <List
    data='{[...]}'
    groupBy="{(item) => item.name[0]}">
    <property name="groupHeaderTemplate">
      <VStack>
        <Text variant="subtitle" value="{$group.key}" />
      </VStack>
    </property>
  </List>
</App>

groupFooterTemplate

Enables the customization of how the the footer of each group is displayed. Combine with groupHeaderTemplate to customize sections. You can use the $item context variable to access an item group and map its individual attributes.

The structure of $group in a groupFooterTemplate is the following:

This example displays a separator line in the groups' footer:

<App>
  <List data='{[...]}' groupBy="category">
    <property name="groupHeaderTemplate">
      <VStack>
        <Text variant="subtitle" value="{$group.key}" />
      </VStack>
    </property>
    <property name="groupFooterTemplate">
      <VStack paddingVertical="$space-normal">
        <ContentSeparator/>
      </VStack>
    </property>
  </List>
</App>

groupHeaderTemplate

Enables the customization of how the groups are displayed, similarly to the itemTemplate. You can use the $item context variable to access an item group and map its individual attributes.

The structure of $group in a groupHeaderTemplate is the following:

<App>
  <List data='{[...]}' groupBy="category">
    <property name="groupHeaderTemplate">
      <Stack padding="$space-2">
        <Text variant="subtitle" value="{$group.key}" />
      </Stack>
    </property>
  </List>
</App>

groupsInitiallyExpanded

default: true

This Boolean property defines whether the list groups are initially expanded.

Note how the groups in the right List are expanded by default:

<App>
  <HStack gap="$space-2">
    <List data="{[...]}" 
      groupBy="category" 
      groupsInitiallyExpanded="false" 
      width="$space-48">
      <property name="groupHeaderTemplate">
        <Stack>
          <Text variant="subtitle" value="{$group.key}" />
        </Stack>
      </property>
    </List>
    <List data="{[...]}" 
      groupBy="category" 
      groupsInitiallyExpanded="true" 
      width="$space-48">
      <property name="groupHeaderTemplate">
        <Stack>
          <Text variant="subtitle" value="{$group.key}" />
        </Stack>
      </property>
    </List>
  </HStack>
</App>

hideEmptyGroups

default: true

This boolean property indicates if empty groups should be hidden (no header and footer are displayed).

Note how the meats category is not displayed in the right List:

<App>
  <HStack gap="$space-2">
    <List
      data="{[...]}"
      defaultGroups="{['meats']}"
      groupBy="category"
      hideEmptyGroups="false"
      width="$space-48">
      <property name="groupHeaderTemplate">
        <Stack>
          <Text variant="subtitle" value="{$group.key}" />
        </Stack>
      </property>
    </List>
    <List
      data="{[...]}"
      defaultGroups="{['meats']}"
      groupBy="category"
      hideEmptyGroups="true"
      width="$space-48">
      <property name="groupHeaderTemplate">
        <Stack>
          <Text variant="subtitle" value="{$group.key}" />
        </Stack>
      </property>
    </List>
  </HStack>
</App>

hideSelectionCheckboxes

default: false

If true, hides selection checkboxes. Selection logic still works via API and keyboard.

The default value is false. When set to true, the selection checkboxes are hidden while selection via click, keyboard, and the programmatic API still work as expected.

<App>
  <List 
    data='{[...]}' 
    rowsSelectable="true" 
    enableMultiRowSelection="true" 
    hideSelectionCheckboxes="true"
  >
    <Text>{$item.name}</Text>
  </List>
</App>

idKey

default: "id"

Denotes which attribute of an item acts as the ID or key of the item

<App>
  <List idKey="key" data='{[...]}' />
</App>

initiallySelected

An array of IDs that should be initially selected when the list is rendered. This property only has an effect when the rowsSelectable property is set to true.

The following example pre-selects the first and third items (IDs 0 and 2) when the list renders:

<App>
  <List data='{[...]}' rowsSelectable="true" initiallySelected="{[0, 2]}">
    <Text>{$isSelected ? '✓ ' : ''}{$item.name}</Text>
  </List>
</App>

itemTemplate

This property allows the customization of mapping data items to components. You can use the $item context variable to access an item and map its individual attributes.

Note how in the example below the $item is used to access the name, quantity and unit attributes.

<App>
  <List data='{[...]}'>
    <property name="itemTemplate">
      <Card>
        <HStack verticalAlignment="center">
          <Icon name="info" />
          <Text value="{$item.name}" variant="strong" />
        </HStack>
        <HStack>
          <Text value="{$item.quantity}" />
          <Text value="{$item.unit}" variant="em" />
        </HStack>
      </Card>
    </property>
  </List>
</App>

keyBindings

This property defines keyboard shortcuts for list actions. Provide an object with action names as keys and keyboard shortcut strings as values. Available actions: selectAll, cut, copy, paste, delete. If not provided, default shortcuts are used.

This property uses the following default key bindings:

{ 
  "selectAll": "CmdOrCtrl+A", 
  "cut": "CmdOrCtrl+X", 
  "copy": "CmdOrCtrl+C", 
  "paste": "CmdOrCtrl+V", 
  "delete": "Delete"
}

You can use these accelerator key names:

• CmdOrCtrl: Command on macOS, Ctrl on Windows/Linux
• Alt: Alt/Option
• Shift: Shift
• Super: Command on macOS, Windows key on Windows/Linux
• Ctrl: Control key
• Cmd: Command key (macOS only)

limit

This property limits the number of items displayed in the List. If not set, all items are displayed.

<App>
  <List limit="3" data='{[...]}' />
</App>

loading

This property delays the rendering of children until it is set to false, or the component receives usable list items via the data property.

<App>
  <List loading="true" />
</App>

<App>
  <List loading="true" />
</App>

orderBy

This optioanl property enables the ordering of list items by specifying an attribute in the data.

<App>
  <List orderBy="{{ field: 'quantity', direction: 'desc' }}" data='{[...]}' />
</App>

pageInfo

This property contains the current page information. Setting this property also enures the List uses pagination.

It contains the following boolean attributes:

refreshOn

Bind this property to a global variable (or expression) whose change should force all visible list items to re-render and pick up the latest reactive state. When not set, items re-render on every XMLUI reactive cycle (safe but less optimal). When set, items only re-render when the bound value changes, which eliminates spurious re-renders from unrelated global-variable updates (e.g. focus events).

rowsSelectable

Indicates whether the rows are selectable (true) or not (false).

The default value is false. When enabled, clicking a row selects it and highlights it. The current selection state is exposed to the item template via the $isSelected context variable.

<App>
  <List data='{[...]}' rowsSelectable="true">
    <Text color="{$isSelected ? '$color-primary' : 'inherit'}">{$item.name}</Text>
  </List>
</App>

rowUnselectablePredicate

This property defines a predicate function with a return value that determines if the row should be unselectable. The function retrieves the item to display and should return a Boolean-like value. This property only has an effect when the rowsSelectable property is set to true.

Rows matching this predicate cannot be selected and are excluded from select-all operations. The selection checkbox is automatically displayed as disabled for these rows, providing visual feedback to users.

<App>
  <List data='{[...]}'
    rowsSelectable="true"
    rowUnselectablePredicate="{(item) => item.category === 'vegetables'}">
    <Text>{$item.name}</Text>
  </List>
</App>

scrollAnchor

default: "top"

This property pins the scroll position to a specified location of the list. Available values are shown below.

Available values: top (default), bottom

<App>
  <List scrollAnchor="bottom" data='{[...]}' height="300px" />
</App>

selectionCheckboxAnchor

default: "left-center"

The corner of the item that the overlay checkbox is anchored to. Only applies when selectionCheckboxPosition is "overlay". Offsets are measured inward from the chosen corner.

Available values: top-left, top-right, bottom-left, bottom-right, center-left, center-right

Use "center-left" or "center-right" to vertically center the checkbox regardless of row height — ideal for card-style layouts.

<App>
  <List data='{[...]}' 
    rowsSelectable="true"
    selectionCheckboxPosition="overlay"
    selectionCheckboxAnchor="bottom-left">
    <Card paddingLeft="40px">{$item.name}</Card>
  </List>
</App>

selectionCheckboxOffsetX

default: "$space-2"

Horizontal distance of the overlay checkbox from its anchor corner. Accepts any CSS length value (e.g. "8px", "1rem"). Only applies when selectionCheckboxPosition is "overlay".

selectionCheckboxOffsetY

default: "$space-2"

Vertical distance of the overlay checkbox from its anchor corner. Accepts any CSS length value (e.g. "8px", "1rem"). Only applies when selectionCheckboxPosition is "overlay".

selectionCheckboxPosition

default: "before"

Controls the placement mode of selection checkboxes. "before" (default) renders the checkbox inline before the item content. "overlay" renders the checkbox absolutely positioned inside the item's bounding box, overlapping the content. Use selectionCheckboxAnchor, selectionCheckboxOffsetX, and selectionCheckboxOffsetY to control the overlay position.

Available values: before (default), overlay

When "overlay" is active, use selectionCheckboxAnchor, selectionCheckboxOffsetX, and selectionCheckboxOffsetY to fine-tune the position.

<App>
  <List data='{[...]}' rowsSelectable="true" selectionCheckboxPosition="overlay">
    <Card paddingLeft="40px">{$item.name}</Card>
  </List>
</App>

selectionCheckboxSize

CSS size of the checkbox (e.g. "16px", "20px"). When not set the browser default size is used. Applies in both "before" and "overlay" modes.

Sets the width and height of the checkbox element. Accepts any CSS length value such as "16px" or "20px". When not set the browser default size is used. Applies in both "before" and "overlay" modes.

<App>
  <List data='{[...]}' rowsSelectable="true" selectionCheckboxSize="20px">
    <Text>{$item.name}</Text>
  </List>
</App>

syncWithVar

The name of a global variable to synchronize the list's selection state with. The named variable must reference an object; the list will read from and write to its 'selectedIds' property. When provided, this takes precedence over initiallySelected.

The following example demonstrates two independent MyList components sharing selection state through a global variable. Selecting a row in either list immediately reflects in the other:

syncWithVar works with both global and local variables. When using local variables, ensure all Lists in the sync have that variable in their scope.

<App global.selState="{{}}">
  <MyList />
  <Text>Selection: {JSON.stringify(selState)}</Text>
  <MyList />
</App>

<Component name="MyList">
  <List
    syncWithVar="selState"
    data='{[
  { id: 0, name: "Apples", category: "fruits" },
  { id: 1, name: "Bananas", category: "fruits" },
  { id: 2, name: "Carrots", category: "vegetables" },
  { id: 3, name: "Spinach", category: "vegetables" }
]}'
    rowsSelectable="true"
    enableMultiRowSelection="true"
  >
    <Text>{$item.name} — {$item.category}</Text>
  </List>
</Component>

<App global.selState="{{}}">
  <MyList />
  <Text>Selection: {JSON.stringify(selState)}</Text>
  <MyList />
</App>

<Component name="MyList">
  <List
    syncWithVar="selState"
    data='{[
  { id: 0, name: "Apples", category: "fruits" },
  { id: 1, name: "Bananas", category: "fruits" },
  { id: 2, name: "Carrots", category: "vegetables" },
  { id: 3, name: "Spinach", category: "vegetables" }
]}'
    rowsSelectable="true"
    enableMultiRowSelection="true"
  >
    <Text>{$item.name} — {$item.category}</Text>
  </List>
</Component>

Events

contextMenu

This event is triggered when the List is right-clicked (context menu).

Signature: contextMenu(event: MouseEvent): void

• event: The mouse event object.

copyAction

This event is triggered when the user presses the copy keyboard shortcut (default: Ctrl+C/Cmd+C) and rowsSelectable is set to true.

Signature: copy(row: ListRowContext | null, selectedItems: any[], selectedIds: string[]): void | Promise<void>

• row: The currently focused row context, or null if no row is focused.
• selectedItems: Array of selected row items.
• selectedIds: Array of selected row IDs (as strings).

<App var.log="">
  <Text>{log}</Text>
  <List data='{[...]}' rowsSelectable="true"
    onCopyAction="(row, items, ids) => log = 'Copied: ' + ids.join(', ')">
    <Text>{$item.name}</Text>
  </List>
</App>

cutAction

This event is triggered when the user presses the cut keyboard shortcut (default: Ctrl+X/Cmd+X) and rowsSelectable is set to true.

Signature: cut(row: ListRowContext | null, selectedItems: any[], selectedIds: string[]): void | Promise<void>

• row: The currently focused row context, or null if no row is focused.
• selectedItems: Array of selected row items.
• selectedIds: Array of selected row IDs (as strings).

See also copyAction, pasteAction, and deleteAction for the other keyboard-triggered events.

deleteAction

This event is triggered when the user presses the delete keyboard shortcut (default: Delete key) and rowsSelectable is set to true.

Signature: delete(row: ListRowContext | null, selectedItems: any[], selectedIds: string[]): void | Promise<void>

• row: The currently focused row context, or null if no row is focused.
• selectedItems: Array of selected row items.
• selectedIds: Array of selected row IDs (as strings).

See copyAction for a similar example.

pasteAction

This event is triggered when the user presses the paste keyboard shortcut (default: Ctrl+V/Cmd+V) and rowsSelectable is set to true.

Signature: paste(row: ListRowContext | null, selectedItems: any[], selectedIds: string[]): void | Promise<void>

• row: The currently focused row context, or null if no row is focused.
• selectedItems: Array of selected row items.
• selectedIds: Array of selected row IDs (as strings).

See copyAction for a similar example.

rowDoubleClick

This event is fired when the user double-clicks a list row. The handler receives the clicked row item as its only argument.

Signature: rowDoubleClick(item: any): void

• item: The clicked list row item.

This event is triggered when a list row is double-clicked. The handler receives the row's data item as its only argument.

<App var.lastClicked="">
  <Text>Double-clicked: {lastClicked}</Text>
  <List data='{[...]}' onRowDoubleClick="(item) => lastClicked = item.name">
    <Text>{$item.name}</Text>
  </List>
</App>

selectAllAction

This event is triggered when the user presses the select all keyboard shortcut (default: Ctrl+A/Cmd+A) and rowsSelectable is set to true. The component automatically selects all rows before invoking this handler.

Signature: selectAll(row: ListRowContext | null, selectedItems: any[], selectedIds: string[]): void | Promise<void>

• row: The currently focused row context, or null if no row is focused.
• selectedItems: Array of all selected row items.
• selectedIds: Array of all selected row IDs (as strings).

<App var.log="">
  <Text>{log}</Text>
  <List 
    data='{[...]}' 
    rowsSelectable="true" 
    enableMultiRowSelection="true"
    onSelectAllAction="(row, items, ids) => 
      log = 'Selected all: ' + ids.join(', ')
    ">
    <Text>{$item.name}</Text>
  </List>
</App>

selectionDidChange

This event is triggered when the list's current selection changes. Its parameter is an array of the selected list row items.

Signature: selectionDidChange(selectedItems: any[]): void

• selectedItems: An array of the selected list row items.

The handler receives an array of the selected items. If multi-row selection is disabled, the array will contain zero or one item.

<App var.selection="">
  <Text>Selected: {selection}</Text>
  <List data='{[...]}'
    rowsSelectable="true"
    enableMultiRowSelection="true"
    onSelectionDidChange="(items) => selection = items.map(i => i.name).join(', ')">
    <Text>{$item.name}</Text>
  </List>
</App>

Exposed Methods

clearSelection

This method clears the list of currently selected list rows.

Signature: clearSelection(): void

The following example demonstrates clearSelection and the other selection API methods:

<App>
  <HStack>
    <Button label="Select all" onClick="list.selectAll()" />
    <Button label="Select 0, 2" onClick="list.selectId([0, 2])" />
    <Button label="Clear" onClick="list.clearSelection()" />
  </HStack>
  <List 
    id="list" 
    data='{[...]}' 
    rowsSelectable="true" 
    enableMultiRowSelection="true"
    onSelectionDidChange="(items) => selection = items.map(i => i.id).join(', ')"
  >
    <Text>{$item.name}</Text>
  </List>
</App>

getSelectedIds

This method returns the list of currently selected list row IDs.

Signature: getSelectedIds(): Array<string>

(See the example at the clearSelection method)

getSelectedItems

This method returns the list of currently selected list row items.

Signature: getSelectedItems(): Array<any>

(See the example at the clearSelection method)

scrollToBottom

This method scrolls the list to the bottom.

Signature: scrollToBottom(): void

The following example demonstrates scrollToBottom and all the other scroll methods:

<App layout="condensed-sticky" scrollWholePage="false">
  <AppHeader>
    <HStack>
      <Button onClick="myList.scrollToBottom()">Scroll to Bottom</Button>
      <Button onClick="myList.scrollToTop()">Scroll to Top</Button>
      <Button onClick="myList.scrollToIndex(25)">Scroll to #25</Button>
      <Button onClick="myList.scrollToId('item-40')">Scroll to ID 'item-40'</Button>
    </HStack>
  </AppHeader>
  <List 
    id="myList" 
    height="*"
    data="{
      Array.from({ length: 100 })
      .map((_, i) => ({id: 'item-' + i, value: 'Item #' + i}))
    }">
    <property name="itemTemplate">
      <Card>
        <Text value="{$item.value}" />
      </Card>
    </property>
  </List>
</App>

<App layout="condensed-sticky" scrollWholePage="false">
  <AppHeader>
    <HStack>
      <Button onClick="myList.scrollToBottom()">Scroll to Bottom</Button>
      <Button onClick="myList.scrollToTop()">Scroll to Top</Button>
      <Button onClick="myList.scrollToIndex(25)">Scroll to #25</Button>
      <Button onClick="myList.scrollToId('item-40')">Scroll to ID 'item-40'</Button>
    </HStack>
  </AppHeader>
  <List 
    id="myList" 
    height="*"
    data="{
      Array.from({ length: 100 })
      .map((_, i) => ({id: 'item-' + i, value: 'Item #' + i}))
    }">
    <property name="itemTemplate">
      <Card>
        <Text value="{$item.value}" />
      </Card>
    </property>
  </List>
</App>

scrollToId

This method scrolls the list to a specific item. The method accepts an item ID as a parameter.

Signature: scrollToId(id: string): void

• id: The ID of the item to scroll to.

See the scrollToBottom example.

scrollToIndex

This method scrolls the list to a specific index. The method accepts an index as a parameter.

Signature: scrollToIndex(index: number): void

• index: The index to scroll to.

See the scrollToBottom example.

scrollToTop

This method scrolls the list to the top.

Signature: scrollToTop(): void

See the scrollToBottom example.

selectAll

This method selects all the rows in the list. This method has no effect if the rowsSelectable property is set to false.

Signature: selectAll(): void

(See the example at the clearSelection method)

selectId

This method selects the row with the specified ID. This method has no effect if the rowsSelectable property is set to false. The method argument can be a single id or an array of them.

Signature: selectId(id: string | Array<string>): void

• id: The ID of the row to select, or an array of IDs to select multiple rows.

(See the example at the clearSelection method)

Styling

List supports the following theme variables for customizing selection colors and the appearance of selection checkboxes.

Selection colors:

Selection checkbox appearance — each variable falls back to the equivalent Checkbox component theme variable when not explicitly set, so the checkboxes automatically follow your form input styling:

Theme Variables