tuix-table

tuix-table draws the rows you give it. It never sorts, filters or slices them by itself.

Sorting and pagination are controlled. The table reports what the user clicked and your application decides what happens next:

Nothing moves in the table until that last step runs. Every example below shows it in Angular, Vue and React.

A first table

Two properties are enough: headers describes the columns, data holds the rows.

const table = document.querySelector('tuix-table')
 
table.headers = [
    { name: 'ID', dataKey: 'id', width: 10 },
    { name: 'Invoice', dataKey: 'name', width: 30 },
    {
        name: 'Status',
        dataKey: 'status',
        width: 20,
        cellColor: (row) => (row.status === 'Error' ? TextVariant.ERROR : TextVariant.SUCCESS),
    },
]
 
table.data = [{ id: 1, name: 'INV-2024-114', status: 'Success' }]

Headers

One object per column. Only dataKey and width are required.

interface IDataTableHeader<TRowData = Record<string, unknown>> {
    name?: string
    dataKey: keyof TRowData
    width: number
    isSlot?: boolean
    slotName?: string
    sortKey?: keyof TRowData
    cellColor?: (rowData: TRowData) => string | undefined
    cellBackgroundColor?: (rowData: TRowData) => string | undefined
}

Column widths

width is a weight, not a pixel value. The widths of all columns are added up and each column takes its share, so 10 / 30 / 20 and 1 / 3 / 2 give the same layout. When every width is 0, the columns share the space evenly.

Slotted cells

With isSlot: true the cell prints <slot name="{slotName}-{row.id}"> instead of a value. The row id is part of the slot name, so every cell has a slot of its own:

A slot takes as many elements as the row needs. The example puts an archive icon and a notify icon in each cell. The framework tabs show that same pair as an @for block, a v-for and a map.

Sorting

The table draws the sorting controls. Your application does the sorting.

A column with a sortKey gets the chevron pair, becomes focusable and reacts to a click, to Enter and to Space. Every column below is sortable:

The three steps

table.headers = [{ name: 'Invoice', dataKey: 'name', sortKey: 'name', width: 30 }]

table.addEventListener('sort', (event) => {
    const { sortKey, sortDirection } = event.detail
})

table.data = sortRows(rows, sortKey, sortDirection)
table.sortBy = sortKey
table.sortDirection = sortDirection

Sorting the rows

Array.prototype.sort sorts in place, so sort a copy. The new array is also what React, Vue and Angular need in order to redraw:

const compare = (a: Invoice, b: Invoice, key: keyof Invoice) => {
    const left = a[key]
    const right = b[key]
    return typeof left === 'number' && typeof right === 'number'
        ? left - right
        : String(left).localeCompare(String(right))
}
 
const sortRows = (rows: Invoice[], sortKey: keyof Invoice, sortDirection: SortDirection) =>
    [...rows].sort((a, b) => (sortDirection === 'asc' ? 1 : -1) * compare(a, b, sortKey))

A few things to keep in mind:

• Compare by type. The default comparison is by text, which puts 10 before 2. Subtract numbers, send text through localeCompare, and compare dates by their timestamps.
• Decide where empty values go. A field that can be null needs a rule of its own, so those rows always land on the same side.
• One column at a time. The detail never carries a second key. Ordering by more than one column is your code's job, behind the same event.
• Paginated tables sort the whole set, not the page on screen. Sort on the server, ask for the first page of the new order and set currentPage back to 1. The table does not reset it for you.
• Leave sortBy unset until a column is clicked. No chevron is highlighted then, and the rows print in the order you gave them.

Pagination

Same contract as sorting: the footer asks, your code answers. The demo pages through 23 rows.

table.addEventListener('next-page', (event) => {
    load(event.detail.page, event.detail.pageSize)
})

The chevrons stop at the first and at the last page, which the table works out from totalItems and the page size. Choosing another page size always asks for page 1.

Loading

isLoadingData replaces the rows with a loader. The header row and the pagination footer stay, and the page-size select is disabled:

loader shapes it, and every field is optional:

Responsive behaviour

disableMobileTable keeps the table layout at every width. The layout is fixed: a cell that overflows scrolls on its own instead of wrapping, and the table scrolls sideways when the columns no longer fit its 650px minimum.

API

Properties

data, headers, pageSizeOptions and loader are array and object properties, so their attributes read JSON (data='[{"id":1}]'). Only the property can carry the functions a header may hold, such as cellColor.

Events

All four bubble and cross the shadow boundary, and all four carry the state the table is asking for:

TypeScript

TuixTableElement<TRowData> types a reference to the element with all its properties, which is what a useRef or a querySelector needs:

import type { TuixTableElement, IDataTableHeader } from 'tuix-webcomponents'
 
const table = document.querySelector('tuix-table') as TuixTableElement<Invoice>
const headers: IDataTableHeader<Invoice>[] = [{ name: 'ID', dataKey: 'id', width: 10 }]