Table

Table presents structured data for viewing, sorting, selection, and interaction.

Key features:

• Data integration: Load data from APIs via DataSource or use static arrays
• Virtualization: Only renders visible rows for smooth performance with large datasets
• Row selection: Support single or multi-row selection for bulk operations
• Pagination: Built-in pagination controls for managing large datasets

Use Column to define headers, data binding, sorting behavior, and custom cell content.

In the following sections the examples use data with the structure outlined below:

The data is provided as JSON. In the source code samples, the data={[...]} declaration represents the data above.

All samples use table columns with the following definition unless noted otherwise (The ... declaration nested into <Table> represents this column definition):

<Table data='{[...]}'>
  <Column bindTo="name"/>
  <Column bindTo="quantity"/>
  <Column bindTo="unit"/>
</Table>

Note: See Column to learn more about table columns.

Behaviors

This component supports the following behaviors:

Properties

alwaysShowHeader

default: false

This property indicates whether the table header is always visible when scrolling and no height is specified. When set to true, the header is sticky and always visible on page scroll. Otherwise, it scrolls with the content and may not be visible when scrolled down.

alwaysShowPagination

This property explicitly toggles pagination controls visibility. If set to true, controls are always shown even if there is only one page. If set to false, controls are hidden. If omitted, controls are hidden when there is only one page and shown otherwise. This property only has effect when pagination is enabled. It acts as an alias for showPaginationControls.

alwaysShowSelectionCheckboxes

default: false

When set to true, selection checkboxes are always visible for all rows instead of appearing only on hover. Has no effect when hideSelectionCheckboxes is true or when row selection is disabled.

alwaysShowSelectionCheckboxesHeader

default: false

This property indicates when the row selection header is displayed. When the value is true, the selection header is always visible. Otherwise, it is displayed only when hovered.

alwaysShowSortingIndicator

default: false

This property indicates whether the sorting indicator is always visible in the column headers. When set to true, the sorting indicator is always visible. Otherwise, it is visible only when the user hovers over/focuses the column header or the column is sorted.

autoFocus

default: false

If this property is set to true, the component gets the focus automatically when displayed.

buttonRowPosition

default: "center"

Determines where to place the pagination button row in the layout. It works the same as the Pagination component property.

Available values: start, center (default), end

cellVerticalAlign

default: "center"

This property controls the vertical alignment of cell content. It can be set to top, center, or bottom.

Available values: top, center (default), bottom

checkboxTolerance

default: "compact"

This property controls the tolerance area around checkboxes for easier interaction. This property only has an effect when the rowsSelectable property is set to true. none provides no tolerance (0px), compact provides minimal tolerance (8px), comfortable provides medium tolerance (12px), and spacious provides generous tolerance (16px) for improved accessibility.

Available values: none, compact (default), comfortable, spacious

The default value is false.

<App>
  <Table data='{[...]}' 
    rowsSelectable="true"
    checkboxTolerance="comfortable"
  >
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

data

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

<App>
  <Table data='{[...]}'>
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

You can also provide the Table with data directly from an API via this property. Here, the component displays rocket information coming from the official SpaceX API.

<App>
  <Table data='https://api.spacexdata.com/v3/rockets'>
    <Column header="Image" size="140px">
      <Image height="100px" fit="cover" src="{$item.flickr_images[0]}"/>
    </Column>
    <Column canSort="true" bindTo="country"/>
    <Column canSort="true" bindTo="company"/>
  </Table>
</App>

<App>
  <Table data='https://api.spacexdata.com/v3/rockets'>
    <Column header="Image" size="140px">
      <Image height="100px" fit="cover" src="{$item.flickr_images[0]}"/>
    </Column>
    <Column canSort="true" bindTo="country"/>
    <Column canSort="true" bindTo="company"/>
  </Table>
</App>

enableMultiRowSelection

default: true

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

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

By default, the value of this property is true.

<App>
  <Table data='{[...]}' 
    rowsSelectable="true" 
    enableMultiRowSelection="false">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

headerHeight

This optional property is used to specify the height of the table header.

It accepts common size values.

<App>
  <Table data='{[...]}' headerHeight="60px">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

hideHeader

default: false

Set the header visibility using this property. Set it to true to hide the header.

Set the header visibility using this property. Set it to true to hide the header. The default value is false.

<App>
  <Table data='{[...]}' hideHeader="true">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

hideSelectionCheckboxes

default: false

If true, hides selection checkboxes for both rows and header. Selection logic still works via API and keyboard.

Hides the selection checkboxes in both the header and rows while keeping the selection API and keyboard selection behavior intact. Useful when you want selection functionality without visible checkboxes.

The default value is false.

<App>
  <Table data='{[...]}' rowsSelectable="true" enableMultiRowSelection="true" hideSelectionCheckboxes="true">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

iconNoSort

Allows setting an alternate icon displayed in the Table column header when sorting is enabled, but the column remains unsorted. You can change the default icon for all Table instances with the "icon.nosort:Table" declaration in the app configuration file.

Allows the customization of the icon displayed in a Table column header when when sorting is enabled and sorting is not done according to the column. Use the "-" (dash) value to sign that you do not want to display an icon when a table column is not sorted.

<App>
  <Table data='{[...]}' sortBy="quantity" iconNoSort="close">
    <Column bindTo="name" canSort="true" />
    <Column bindTo="quantity" canSort="true" />
    <Column bindTo="unit" canSort="true" />
  </Table>
</App>

iconSortAsc

Allows setting an alernate icon displayed in the Table column header when sorting is enabled, and the column is sorted in ascending order. You can change the default icon for all Table instances with the "icon.sortasc:Table" declaration in the app configuration file.

Allows the customization of the icon displayed in a Table column header when sorting is enabled, sorting is done according to the column, and the column is sorted in ascending order.

<App>
  <Table data='{[...]}' sortBy="quantity" iconSortAsc="chevronup">
    <Column bindTo="name" canSort="true" />
    <Column bindTo="quantity" canSort="true" />
    <Column bindTo="unit" canSort="true" />
  </Table>
</App>

iconSortDesc

Allows setting an alternate icon displayed in the Table column header when sorting is enabled, and the column is sorted in descending order. You can change the default icon for all Table instances with the "icon.sortdesc:Table" declaration in the app configuration file.

Allows the customization of the icon displayed in a Table column header when sorting is enabled, sorting is done according to the column, and the column is sorted in descending order.

<App>
  <Table data='{[...]}' sortBy="quantity" iconSortDesc="chevrondown">
    <Column bindTo="name" canSort="true" />
    <Column bindTo="quantity" canSort="true" />
    <Column bindTo="unit" canSort="true" />
  </Table>
</App>

Select a column header and set it to descending ordering.

idKey

default: "id"

This property is used to specify the unique ID property in the data array. If the idKey points to a property that does not exist in the data items, that will result in incorrect behavior when using selectable rows.

<App>
  <Table
    idKey="key"
    rowsSelectable="true"
    data="{[
      { 'key': 0, 'name': 'John' },
      { 'key': 1, 'name': 'Jane' },
      { 'key': 2, 'name': 'Bill' },
    ]}"
  > 
    <Column bindTo="name"/>
  </Table>
</App>

initiallySelected

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

isPaginated

default: false

This property adds pagination controls to the Table.

<App>
  <Table data='{[...]}' isPaginated="true" pageSizeOptions="{[3, 6, 12]}">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

keyBindings

This property defines keyboard shortcuts for table actions. Provide an object with action names as keys and keyboard shortcut strings as values. The shortcut strings use Electron accelerator syntax (e.g., 'CmdOrCtrl+A', 'Delete'). 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/Options
• Shift: Shift
• Super: Command on macOS, Windows key on Windows/Linux
• Ctrl: Control key
• Cmd: Command key (macOS only)

loading

This boolean property indicates if the component is fetching (or processing) data. This property is useful when data is loaded conditionally or receiving it takes some time.

This boolean property indicates if the component is fetching (or processing) data. This property is useful when data is loaded conditionally or receiving it takes some time.

<App>
  <Table loading="true">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
  </Table>
</App>

<App>
  <Table loading="true">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
  </Table>
</App>

noBottomBorder

default: false

This property indicates whether the table should have a bottom border. When set to true, the table does not have a bottom border. Otherwise, it has a bottom border.

noDataTemplate

A property to customize what to display if the table does not contain any data.

<App>
  <Table>
    <property name="noDataTemplate">
      <Text value="No data loaded" variant="strong" />
    </property>
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
  </Table>
</App>

<App>
  <Table>
    <property name="noDataTemplate">
      <Text value="No data loaded" variant="strong" />
    </property>
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
  </Table>
</App>

pageInfoPosition

Determines where to place the page information in the layout. It works the same as the Pagination component property.

pageSize

This property defines the number of rows to display per page when pagination is enabled.

Options

Page sizes are only accepted in an array, even if the array contains one item.

Note that this property only works if the isPaginated property is set to true.

<App>
  <Table data='{[...]}' isPaginated="true" pageSizeOptions="{[3, 6, 12]}">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

pageSizeOptions

This property holds an array of page sizes (numbers) the user can select for pagination. If this property is not defined, the component allows only a page size of 10 items.

Page sizes are only accepted in an array, even if the array contains one item.

Note that this property only works if the isPaginated property is set to true.

<App>
  <Table data='{[...]}' isPaginated="true" pageSizeOptions="{[3, 6, 12]}">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

pageSizeSelectorPosition

Determines where to place the page size selector in the layout. It works the same as the Pagination component property.

paginationControlsLocation

default: "bottom"

This property determines the location of the pagination controls. It can be set to top, bottom, or both.

Available values: top, bottom (default), both

rowDisabledPredicate

This property defines a predicate function with a return value that determines if the row should be disabled. The function retrieves the item to display and should return a Boolean-like value.

The following example disables all table rows where the item's quantity exceeds 6:

<App>
  <Table data='{[...]}'
    rowDisabledPredicate="{(item) => item.quantity > 6}">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

Disabled items are rendered with a different color.

rowsSelectable

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

The default value is false.

<App>
  <Table data='{[...]}' rowsSelectable="true">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</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.

showCurrentPage

default: true

Whether to show the current page indicator. It works the same as the Pagination component property.

showPageInfo

default: true

Whether to show page information. It works the same as the Pagination component property.

showPageSizeSelector

default: true

Whether to show the page size selector. It works the same as the Pagination component property.

sortBy

This property is used to determine which data property to sort by. If not defined, the data is not sorted

<App>
  <Table data='{[...]}' sortBy="quantity">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

sortDirection

This property determines the sort order to be ascending or descending. This property only works if the sortBy property is also set. By default ascending order is used.

<App>
  <Table data='{[...]}' sortBy="quantity" sortDirection="descending">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

syncWithAppState

An AppState instance to synchronize the table's selection state with. The table will read from and write to the 'selectedIds' property of the AppState object. When provided, this takes precedence over the initiallySelected property for initial selection. You can use the AppState's didUpdate event to receive notifications when the selection changes.

userSelectCell

default: "auto"

This property controls whether users can select text within table cells. Use text to allow text selection, none to prevent selection, or auto for default behavior.

Available values:

userSelectHeading

default: "none"

This property controls whether users can select text within table headings. Use text to allow text selection, none to prevent selection, or auto for default behavior.

Available values:

userSelectRow

default: "auto"

This property controls whether users can select text within table rows. Use text to allow text selection, none to prevent selection, or auto for default behavior.

Available values:

Events

contextMenu

This event is triggered when the Table 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. The handler receives three parameters: the focused row, selected items, and selected IDs. The handler should implement the copy logic (e.g., using the Clipboard API to copy selected data).

Signature: copy(row: TableRowContext | 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).

cutAction

This event is triggered when the user presses the cut keyboard shortcut (default: Ctrl+X/Cmd+X) and rowsSelectable is set to true. The handler receives three parameters: the focused row, selected items, and selected IDs. Note: The component does not automatically modify data; the handler must implement the cut logic (e.g., copying data to clipboard and removing from the data source).

Signature: cut(row: TableRowContext | 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).

deleteAction

This event is triggered when the user presses the delete keyboard shortcut (default: Delete key) and rowsSelectable is set to true. The handler receives three parameters: the focused row, selected items, and selected IDs. Note: The component does not automatically remove data; the handler must implement the delete logic (e.g., removing selected items from the data source).

Signature: delete(row: TableRowContext | 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).

pasteAction

This event is triggered when the user presses the paste keyboard shortcut (default: Ctrl+V/Cmd+V) and rowsSelectable is set to true. The handler receives three parameters: the focused row, selected items, and selected IDs. The handler must implement the paste logic (e.g., reading from clipboard and inserting data into the table).

Signature: paste(row: TableRowContext | 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).

rowDoubleClick

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

Signature: rowDoubleClick(item: any): void

• item: The clicked table row item.

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

<App>
  <Table data='{[...]}' onRowDoubleClick="(item) => console.log(item)">
    <Column bindTo="name"/>

%-EVENT-START rowDoubleClick

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

```xmlui copy {4}
<App>
  <Table data='{[...]}' onRowDoubleClick="(item) => console.log(item)">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
  </Table>
</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. The handler receives three parameters: the currently focused row (if any), all selected items, and all selected IDs.

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

• row: The currently focused row context, or null if no row is focused. Contains item data, row index, row ID, and selection state.
• selectedItems: Array of all selected row items. When selectAll is triggered, this contains all table rows.
• selectedIds: Array of all selected row IDs (as strings). When selectAll is triggered, this contains all row IDs.

selectionDidChange

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

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

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

Of course, if multiple-row selection is not allowed (enableMultipleRowSelection is false), this array will contain zero or one item.

<App var.selection="">
  <Text>Current selection (row IDs): [{selection}]</Text>
  <Table data='{[...]}'
    rowsSelectable="true"
    enableMultiRowSelection="true"
    onSelectionDidChange="(newSel) => selection = newSel.map(item => item.id).join()" >
    <Column bindTo="name" canSort="true"/>
    <Column bindTo="quantity" canSort="true"/>
    <Column bindTo="unit" canSort="true"/>
  </Table>
</App>

Click on any of the column headers to trigger a new sorting:

sortingDidChange

This event is fired when the table data sorting has changed. It has two arguments: the column's name and the sort direction. When the column name is empty, the table displays the data list as it received it.

Signature: sortingDidChange(columnName: string, sortDirection: 'asc' | 'desc' | null): void

• columnName: The name of the column being sorted.
• sortDirection: The sort direction: 'asc' for ascending, 'desc' for descending, or null for unsorted.

Note the canSort properties on the Column components which enable custom ordering.

<App var.sortedBy="">
  <Heading level="h4" value="Table is sorted by: {sortedBy || ''}" paddingLeft="1rem"/>
  <Table data='{[...]}'
    onSortingDidChange="(by, dir) => sortedBy = (by && dir) ? by + ' | ' + dir : '' " >
    <Column bindTo="name" canSort="true"/>
    <Column bindTo="quantity" canSort="true"/>
    <Column bindTo="unit" canSort="true"/>
  </Table>
</App>

Click on any of the column headers to trigger a new sorting:

willSort

This event is fired before the table data is sorted. It has two arguments: the column's name and the sort direction. When the method returns a literal false value (and not any other falsy one), the method indicates that the sorting should be aborted.

Signature: willSort(columnName: string, sortDirection: 'asc' | 'desc'): boolean | void

• columnName: The name of the column about to be sorted.
• sortDirection: The intended sort direction: 'asc' for ascending or 'desc' for descending.

The following example uses the willSort event to refuse sorting by name:

<App var.sortedBy="">
  <Heading level="h4" value="Table is sorted by: {sortedBy || ''}" paddingLeft="1rem"/>
  <Table data='{[...]}'
    onWillSort="(by, dir) => by !== 'name'"
    onSortingDidChange="(by, dir) => sortedBy = (by && dir) ? by + ' | ' + dir : '' " >
    <Column bindTo="name" canSort="true"/>
    <Column bindTo="quantity" canSort="true"/>
    <Column bindTo="unit" canSort="true"/>
  </Table>
</App>

Click on any of the column headers to trigger the event. Though sorting is enabled in the TableColumnnDef component of the "name" column via canSort, clicking that column header still does not sort because willSort prevents it:

Exposed Methods

clearSelection

This method clears the list of currently selected table rows.

Signature: clearSelection(): void

<App>
  <HStack>
    <Button label="Select all" onClick="table.selectAll()" />
    <Button label="Clear all" onClick="table.clearSelection()" />
    <Button label="Select 1" onClick="table.selectId(1)" />
    <Button label="Select 2, 4" onClick="table.selectId([2, 4])" />
  </HStack>
  <Table id="table" data='{[...]}'
    rowsSelectable="true"
    enableMultiRowSelection="true">
    <Column bindTo="name" canSort="true"/>
    <Column bindTo="quantity" canSort="true"/>
    <Column bindTo="unit" canSort="true"/>
  </Table>
</App>

getSelectedIds

This method returns the list of currently selected table rows IDs.

Signature: getSelectedIds(): Array<string>

(See the example at the clearSelection method)

getSelectedItems

This method returns the list of currently selected table rows items.

Signature: getSelectedItems(): Array<TableRowItem>

(See the example at the clearSelection method)

selectAll

This method selects all the rows in the table. 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)

Parts

The component has some parts that can be styled through layout properties and theme variables separately:

• pagination: The pagination controls container.
• table: The main table container.

Styling

Theme Variables