Table

Table is a component that displays cells organized into rows and columns. The Table component is virtualized so it only renders visible cells.

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.

Properties

alwaysShowSelectionHeader (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.

autoFocus (default: false)

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

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>

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>

iconNoSort

Allows setting the icon displayed in the Table column header when sorting is enabled, but the column remains unsorted.

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 the icon displayed in the Table column header when sorting is enabled, and the column is sorted in ascending order.

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 the icon displayed in the Table column header when sorting is enabled, and the column is sorted in descending order.

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.

isPaginated (default: false)

This property adds pagination controls to the Table.

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

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>

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>

pageSizes

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" pageSizes="{[3, 6, 12]}">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
    <Column bindTo="unit"/>
  </Table>
</App>

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>

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>

sortBy

This property is used to determine which data attributes to sort by.

<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.

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

Events

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.

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.

Note the canSort properties on the TableColumnDef 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.

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.

<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='{${JSON.stringify(data, null, 2)}}'
    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.

(See the example at the clearSelection method)

getSelectedItems

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

(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.

(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.

(See the example at the clearSelection method)

Styling

The Table component uses the following theme variables.

Overall Table theme variables:

• backgroundColor-Table
• borderStyle-cell-Table
• backgroundColor-pagination-Table
• textColor-Table
• textColor-pagination-Table

Row theme variables:

• backgroundColor-row-Table
• backgroundColor-row-Table--hover
• fontSize-row-Table
• fontWeight-row-Table

Selected row theme variables:

• backgroundColor-selected-Table
• backgroundColor-selected-Table--hover

Cell theme variables:

• border-cell-Table
• borderColor-cell-Table
• borderWidth-cell-Table
• padding-cell-Table
• paddingHorizontal-cell-Table
• paddingVertical-cell-Table
• paddingHorizontal-cell-first-Table
• paddingHorizontal-cell-last-Table

Heading theme variables:

• backgroundColor-heading-Table
• backgroundColor-heading-Table--hover
• backgroundColor-heading-Table--active
• textColor-heading-Table
• fontSize-heading-Table
• fontWeight-heading-Table
• padding-heading-Table
• paddingHorizontal-heading-Table
• paddingVertical-heading-Table
• textTransform-heading-Table

Example

{
  "id": "custom",
  "name": "Custom Theme",
  "themeVars": {
    "backgroundColor-heading-Table": "#c4c4c4",
    "backgroundColor-Table": "#ededed",
    "paddingVertical-heading-Table": "1rem",
    "textColor-Table": "black",
    "textColor-heading-Table": "black"
  }
}

Theme Variables