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
• Inferred columns: Display object arrays even when no Column children are provided

Use Column to define headers, data binding, sorting behavior, display types, and custom cell content. If you omit Column children, Table inspects the data records and creates inferred columns automatically. Explicit Column children always win over inferred columns. Inferred columns use idKey to identify the row identifier column, so the default idKey="id" infers an id display type for an id field. UUID-shaped string values infer the more specific uuid display type.

Row identity: The Table uses the id field of each data item as a unique row identifier. This identifier is used for row selection, selectId(), getSelectedIds(), and syncWithVar. If your data uses a different field as the key, set the idKey property to that field name.

Table keeps a bounded cache of recently rendered virtualized rows by default. This reduces remount and measurement flash when users scroll back through content they have already seen. Set renderCache="{false}" to minimize mounted DOM nodes, tune renderCacheSize for the number of recently rendered rows to retain, and use virtualBufferSize when fast scrolling should prepare more never-seen rows just outside the viewport.

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.

The simplest table can render directly from structured data:

When you provide explicit columns, the table renders only those columns:

Inferred columns with bound fields are sortable by default:

Context variables available during execution:

• $cell: The value of the current cell for this column.
• $colIndex: Zero-based index of the current column.
• $item: The complete data row object being rendered.
• $itemIndex: Zero-based index of the row in the data array.
• $row: The complete data row object being rendered (alias of $item).
• $rowIndex: Zero-based row index (alias of $itemIndex).

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

canResizeColumns

default: true

Indicates whether columns can be resized by dragging their header borders. Individual Column components can override this table-level default with their own canResize property.

Set canResizeColumns to false to prevent users from resizing all table columns by default. The default is true.

Individual Column components can override this table-level default with their own canResize property.

cellUserSelect

default: "none"

This property controls whether users can select text within table cells.

Available values:

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>

columnInference

default: "first-n(25)"

Controls how the Table samples the resolved data array when it has no explicit Column children and needs to infer columns and display types. The default is first-n(25). Use first-only for the fastest inference, first-n(n) for a bounded prefix, sample(n) for deterministic spread sampling, all for small datasets, or off to disable inferred columns. This setting inspects row objects only; unwrap API response envelopes before passing data to the table.

columnInference controls how Table samples data when no Column children are provided. The default is first-n(25), which inspects the first 25 records and infers both field names and display types from those sampled values.

Useful values:

• first-only: infer from the first row only
• first-n(25): infer from the first 25 rows; this is the default
• sample(25): infer from a deterministic spread of rows
• all: inspect every row; use this only for small datasets
• off: do not infer columns

The 25 in first-n(25) and sample(25) is only an example. Use any positive integer that fits the data size and cost you want, such as first-n(5), first-n(100), or sample(50).

columnInference expects the table's data value to be the row array itself. If an API returns an envelope such as { items: [...] }, unwrap that envelope before passing the value to Table.

How Inference Works

Column inference runs only when the Table has no explicit Column children. If you add any Column children, those columns define the table instead of the inferred columns.

The table expects data to resolve to an array of row objects. Only plain object rows participate in field discovery; primitive values, arrays, dates, inherited properties, and non-enumerable properties are ignored. The internal order field is also skipped.

Type inference ignores null, undefined, and empty string values when deciding the type. If no present values remain, or if the sampled values are mixed in a way the table cannot classify, the type falls back to text.

Inference is display-oriented. It does not validate data, mutate rows, unwrap API response envelopes, or inspect server-side pages that are not present in the supplied data array. Use explicit Column children when you need guaranteed columns, labels, ordering, types, sizing, or custom cell content.

<App>
  <Table
    columnInference="first-only"
    data='{[
      { id: 1, customer: "Ada" },
      { id: 2, customer: "Grace", total: 87.5 }
    ]}'
  />
</App>

<App>
  <Table
    columnInference="first-only"
    data='{[
      { id: 1, customer: "Ada" },
      { id: 2, customer: "Grace", total: 87.5 }
    ]}'
  />
</App>

Use first-n(n) when the first record may be sparse, but the useful fields appear near the beginning of the data:

<App>
  <Table
    columnInference="first-n(3)"
    data='{[
      { id: 1, customer: "Ada" },
      { id: 2, customer: "Grace", total: 87.5 },
      { id: 3, customer: "Linus", paid: true },
      { id: 4, customer: "Margaret", internalNote: "Not sampled" }
    ]}'
  />
</App>

<App>
  <Table
    columnInference="first-n(3)"
    data='{[
      { id: 1, customer: "Ada" },
      { id: 2, customer: "Grace", total: 87.5 },
      { id: 3, customer: "Linus", paid: true },
      { id: 4, customer: "Margaret", internalNote: "Not sampled" }
    ]}'
  />
</App>

Use sample(n) when fields may appear later in a larger local array and you want a deterministic spread instead of only the first records:

<App>
  <Table
    columnInference="sample(3)"
    data='{[
      { id: 1, customer: "Ada" },
      { id: 2, customer: "Grace" },
      { id: 3, customer: "Linus", total: 87.5 },
      { id: 4, customer: "Margaret" },
      { id: 5, customer: "Katherine", status: "paid" }
    ]}'
  />
</App>

<App>
  <Table
    columnInference="sample(3)"
    data='{[
      { id: 1, customer: "Ada" },
      { id: 2, customer: "Grace" },
      { id: 3, customer: "Linus", total: 87.5 },
      { id: 4, customer: "Margaret" },
      { id: 5, customer: "Katherine", status: "paid" }
    ]}'
  />
</App>

idKey also guides inferred display types. The field named by idKey is inferred as id; UUID-shaped string values are inferred as uuid.

<App>
  <Table
    idKey="customerId"
    data='{[
      {
        customerId: "C-001",
        name: "Ada",
        traceId: "47f4d9f8-2f6a-4e3d-9bf5-010d74822c6f"
      },
      {
        customerId: "C-002",
        name: "Grace",
        traceId: "550e8400-e29b-41d4-a716-446655440000"
      }
    ]}'
  />
</App>

<App>
  <Table
    idKey="customerId"
    data='{[
      {
        customerId: "C-001",
        name: "Ada",
        traceId: "47f4d9f8-2f6a-4e3d-9bf5-010d74822c6f"
      },
      {
        customerId: "C-002",
        name: "Grace",
        traceId: "550e8400-e29b-41d4-a716-446655440000"
      }
    ]}'
  />
</App>

columnSizing

default: "auto"

Controls how automatically sized columns consume horizontal space. stretch keeps the traditional equal-fill behavior, balanced uses type-aware defaults so compact types such as IDs and numbers stay narrow while text-like columns use star sizing, content prefers compact fixed widths, and auto uses balanced for inferred columns while preserving stretch for explicit columns.

Available values: auto (default), stretch, balanced, content

columnSizing controls how automatically sized columns consume horizontal space.

Available values:

• auto: use type-aware balanced sizing for inferred columns, and preserve the traditional stretch behavior for explicit columns
• stretch: distribute available width among columns that do not specify width
• balanced: keep compact types such as id, numbers, booleans, and dates narrow, while text-like types use star sizing
• content: prefer compact fixed widths for typed columns

Explicit Column values such as width, minWidth, maxWidth, and horizontalAlignment override type-aware defaults.

<App>
  <Table
    columnSizing="balanced"
    data='{[
      { id: 1, customer: "Ada", total: 123.45 },
      { id: 2, customer: "Grace", total: 87.5 }
    ]}'
  />
</App>

<App>
  <Table
    columnSizing="balanced"
    data='{[
      { id: 1, customer: "Ada", total: 123.45 },
      { id: 2, customer: "Grace", total: 87.5 }
    ]}'
  />
</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>

dataRefreshMode

default: "reset"

Controls how the table handles later data refreshes after the initial load. reset keeps the table's default refresh behavior. preserve-state reconciles refreshed data with the current view state for unchanged source row IDs.

Available values: reset (default), preserve-state

Use dataRefreshMode="preserve-state" when a Table receives refreshed data after backend mutations. The table keeps the current scroll position, sort state, pagination state when still valid, column sizing, and row selection for source rows whose idKey values still exist. If deletion leaves the current page beyond the new page count, the table clamps to the last available page.

For a complete backend-style insert, update, and delete workflow, see Preserve collection state across data refreshes.

For mutation flows where only the next refresh should preserve state, call preserveStateOnNextDataRefresh() before updating or refetching the data:

Stable, unique idKey values are required. If an inserted row is outside the current viewport and is present in the current row model, operation: "insert" or scrollTarget: "first-inserted" scrolls it into view after reconciliation. For paginated tables, insert targeting does not switch pages.

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>

headerUserSelect

default: "text"

This property controls whether users can select text within table headers.

Available values:

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>

hideSelectionCheckboxesHeader

default: false

If true, the selection checkbox in the table header is never displayed, not even on hover. Row checkboxes are unaffected. Selection logic still works via API and keyboard.

Hides the selection checkbox in the table header so it is never displayed, not even on hover. Row checkboxes are unaffected. Selection logic still works via the component API and keyboard shortcuts.

The default value is false.

<App>
  <Table data='{[...]}' rowsSelectable="true" enableMultiRowSelection="true" hideSelectionCheckboxesHeader="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. When enabled, the pagination bar is automatically hidden if all rows fit on a single page. You can omit this property and set only pageSize instead — pagination will then activate automatically when the data length exceeds the page size and hide itself when it does not.

<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. While loading is true and no rows are available, the table shows its loading UI after the configured loadingDelay.

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

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

loadingDelay

default: 400

The delay in milliseconds before showing the loading UI. Set to 0 to show immediately, or a higher value to prevent flicker for fast-loading data.

The loadingDelay property controls how many milliseconds the table waits before showing its loading UI. The default is 400, which prevents flicker when data loads quickly. Set it to 0 to show the loading UI immediately.

<App var.isLoading="{false}" var.items="{[]}">
  <Button
    label="Load"
    onClick="isLoading = true; delay(1000); items = [{ id: 1, name: 'Loaded row', quantity: 1 }]; isLoading = false" />
  <Table loading="{isLoading}" loadingDelay="400" data="{items}">
    <Column bindTo="name"/>
    <Column bindTo="quantity"/>
  </Table>
</App>

<App var.isLoading="{false}" var.items="{[]}">
  <Button
    label="Load"
    onClick="isLoading = true; delay(1000); items = [{ id: 1, name: 'Loaded row', quantity: 1 }]; isLoading = false" />
  <Table loading="{isLoading}" loadingDelay="400" data="{items}">
    <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

default: "end"

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 set without also setting isPaginated, pagination is activated automatically whenever the number of data rows exceeds this value and suppressed otherwise. This makes pageSize the minimal way to get auto-activating, auto-hiding pagination: no conditional expressions on isPaginated or the position props are needed.

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

default: "start"

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

refreshOn

An expression whose value change forces all table rows and cells to re-render. Use this to ensure that closure variables bound in row or cell templates are updated when global state changes (e.g. {selectMode}). Without this, virtualized rows might retain stale references to global variables for performance reasons.

renderCache

default: true

Controls whether the table keeps a bounded set of recently rendered virtualized rows mounted while they are outside the viewport. Keeping rows mounted reduces remount and measurement flash when users scroll back through recently viewed content.

renderCacheSize

default: 80

Maximum number of recently rendered virtualized rows to keep mounted when renderCache is enabled. Larger values can make repeat scrolling smoother but retain more DOM nodes.

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>

striped

default: false

When set to true, the table rows alternate between the backgroundColor-evenRow-Table and backgroundColor-oddRow-Table theme variables, creating a striped appearance.

<App>
  <Table data='{[...]}' striped="true">
    <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.

syncWithVar

The name of a global variable to synchronize the table's selection state with. The named variable must reference an object; the table will read from and write to its 'selectedIds' property. When provided, this takes precedence over both initiallySelected and syncWithAppState. Multiple tables sharing the same variable name will keep their selections in sync automatically. A runtime error is signalled if the value is not a valid JavaScript variable name.

The following example demonstrates how two independent MyTable components share selection state through a global variable. Selecting a row in either table immediately reflects in the other, and selState always holds the current selection:

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

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

<Component name="MyTable">
  <Table
    syncWithVar="selState"
    rowsSelectable="true"
    data='{[
      { id: 0, name: "Apples", quantity: 5, unit: "pieces" },
      { id: 1, name: "Bananas", quantity: 6 },
      { id: 2, name: "Carrots", quantity: 100, unit: "grams" },
    ]}'
  >
    <Column bindTo="name" />
    <Column bindTo="quantity" />
    <Column bindTo="unit" />
  </Table>
</Component>

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

<Component name="MyTable">
  <Table
    syncWithVar="selState"
    rowsSelectable="true"
    data='{[
      { id: 0, name: "Apples", quantity: 5, unit: "pieces" },
      { id: 1, name: "Bananas", quantity: 6 },
      { id: 2, name: "Carrots", quantity: 100, unit: "grams" },
    ]}'
  >
    <Column bindTo="name" />
    <Column bindTo="quantity" />
    <Column bindTo="unit" />
  </Table>
</Component>

toggleSelectionOnClick

default: false

When true, a plain click toggles the row's selection state instead of replacing the current selection. Ctrl+Click and Shift+Click behavior is unchanged. Only has an effect when rowsSelectable is true.

When true, a plain click toggles the row's selection state (adds it if not selected, removes it if already selected) instead of replacing the current selection with just that row. This property only has an effect when rowsSelectable is true. Ctrl+Click and Shift+Click behavior is unchanged.

The default value is false.

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

userSelectCell

default: "auto"

This property controls whether users can select text within table cells.

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:

virtualBufferSize

Extra virtualizer buffer, in pixels, to render before and after the viewport. Increase this when fast scrolling reaches rows that have not been rendered before; unlike renderCache, this prepares never-seen rows near the viewport.

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>

scroll

This event fires as the user scrolls the table. The handler receives an object describing the current scroll state. It is only fired for user-driven scrolls; the table's own programmatic scrolls do not trigger it. Use it together with the atEnd flag and the scrollToBottom() method to implement follow-newest and read-pause behavior, or with visibleRange and itemCount to display a visible row range.

Signature: scroll(event: { scrollTop: number, scrollHeight: number, viewportSize: number, atEnd: boolean, visibleRange: { startIndex: number, endIndex: number }, itemCount: number }): void

• event: The scroll state: scrollTop (current scroll offset), scrollHeight (total scrollable size), viewportSize (visible size), and atEnd (true when scrolled to within ~1.5px of the bottom), plus visibleRange and itemCount.

This event fires as the user scrolls the table. The event object includes scrollTop, scrollHeight, viewportSize, atEnd, visibleRange, and itemCount.

It is only fired for user-driven scrolls; the table's own programmatic scrolls do not trigger it. Use visibleRange and itemCount to display the currently visible range while the user scrolls.

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:

visibleRangeDidChange

This event fires when the range of visible table rows changes — whatever caused it: a user scroll, a programmatic scroll, or content growth. Unlike the scroll event, it is not suppressed during the table's own programmatic scrolls, because consumers of the visible range care about what is visible, not why it became visible. It fires only when the range actually shifts (deduplicated by value).

Signature: visibleRangeDidChange(range: { startIndex: number, endIndex: number }): void

• range: The visible range: startIndex (first visible row index) and endIndex (last visible row index), inclusive, in the table's current row order.

This event fires when the visible row range changes. It also fires for non-user-scroll changes, such as initial measurement or programmatic scrolling.

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>

getItemCount

This method returns the number of rows in the table's current virtualized row model. For an unpaginated table, this is the number of rows supplied through data or items; for a paginated table, this is the number of rows on the current page.

Signature: getItemCount(): number

Returns the number of rows in the table's current virtualized row model. Use this with getVisibleRange() to build a display such as 234-245 of 1000.

For paginated tables, this count is the number of rows in the current page's virtualized row model.

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)

getVisibleRange

This method returns the currently visible row range as an object with startIndex and endIndex (inclusive, in the table's current row order). Returns { startIndex: -1, endIndex: -1 } when the table is empty or not yet measured. The pull-style counterpart of the visibleRangeDidChange event.

Signature: getVisibleRange(): { startIndex: number, endIndex: number }

Returns the currently visible row range as { startIndex, endIndex }. Indexes are zero-based and inclusive, so add 1 when displaying them to users.

When the table is empty or not yet measured, the method returns { startIndex: -1, endIndex: -1 }. This is the pull-style counterpart of the visibleRangeDidChange event.

<App
  scrollWholePage="false"
  var.itemCount="{0}"
  var.range="{{ startIndex: -1, endIndex: -1 }}">
  <Text
    variant="strong"
    value="{range.startIndex < 0
      ? 'No rows'
      : (range.startIndex + 1) + '-'
        + (range.endIndex + 1) + ' of ' + itemCount}"
  />
  <Table
    id="table"
    height="*"
    onScroll="(e) => { range = e.visibleRange; itemCount = e.itemCount }"
    onVisibleRangeDidChange="(r) => {
      range = r;
      itemCount = table.getItemCount()
    }"
    data="{Array.from({ length: 1000 }, (_, i) => ({
      id: i + 1,
      name: 'Item ' + (i + 1),
      quantity: (i % 25) + 1,
    }))}">
    <Column bindTo="id" width="90px" />
    <Column bindTo="name" />
    <Column bindTo="quantity">
      <Text height="50px">{$cell}</Text>
    </Column>
  </Table>
</App>

<App
  scrollWholePage="false"
  var.itemCount="{0}"
  var.range="{{ startIndex: -1, endIndex: -1 }}">
  <Text
    variant="strong"
    value="{range.startIndex < 0
      ? 'No rows'
      : (range.startIndex + 1) + '-'
        + (range.endIndex + 1) + ' of ' + itemCount}"
  />
  <Table
    id="table"
    height="*"
    onScroll="(e) => { range = e.visibleRange; itemCount = e.itemCount }"
    onVisibleRangeDidChange="(r) => {
      range = r;
      itemCount = table.getItemCount()
    }"
    data="{Array.from({ length: 1000 }, (_, i) => ({
      id: i + 1,
      name: 'Item ' + (i + 1),
      quantity: (i % 25) + 1,
    }))}">
    <Column bindTo="id" width="90px" />
    <Column bindTo="name" />
    <Column bindTo="quantity">
      <Text height="50px">{$cell}</Text>
    </Column>
  </Table>
</App>

preserveStateOnNextDataRefresh

Preserve the current table view state for the next data refresh, even when dataRefreshMode is reset. Optional operation metadata controls post-refresh scroll behavior.

Signature: preserveStateOnNextDataRefresh(options?: { operation?: "insert" | "delete" | "update", scrollTarget?: string | number | "first-inserted" | "preserve" }): void

scrollToBottom

This method scrolls the table to the bottom.

Signature: scrollToBottom(): void

See the getVisibleRange example for displaying the visible range while scrolling.

scrollToId

This method scrolls the table to a specific row. The method accepts a row ID as a parameter.

Signature: scrollToId(id: string): void

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

See the getVisibleRange example.

scrollToIndex

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

Signature: scrollToIndex(index: number): void

• index: The row index to scroll to.

See the getVisibleRange example.

scrollToTop

This method scrolls the table to the top.

Signature: scrollToTop(): void

See the getVisibleRange example.

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