sp-table

NPM

1.0.0

Storybook

View Storybook

Examples

API

Changelog

Attributes and Properties #

Property

Attribute

Type

Default

Description

density

'compact' | 'spacious' | undefined

Changes the spacing around table cell content.

emphasized

boolean

false

Deliver the Table with additional visual emphasis to selected rows.

itemValue

The value of an item. By default, it is set to the index of the sp-table-row.

items

Record<string, unknown>[]

[]

The content of the rows rendered by the virtualized table. The key is the value of the sp-table-row, and the value is the sp-table-row's content (not the row itself).

quiet

boolean

false

Display with "quiet" variant styles.

role

string

'grid'

scroller

boolean

false

Whether or not the virtualized table has a scroll bar. If this is set to true, make sure to specify a height in the sp-table's inline styles.

selected

string[]

[]

An array of values that have been selected.

selects

undefined | 'single' | 'multiple'

Whether the Table allows users to select a row or rows, and thus controls whether or not the Table also renders checkboxes.

Events #

Name

Type

Description

change

Event

Announces a change in the `selected` property of a table row

undefined

RangeChangedEvent

rangeChanged

Event

Announces a change in the range of visible cells on the table body

1.0.0 (2024-10-31) #

Note: Version bump only for package @spectrum-web-components/table

0.49.0 (2024-10-15) #

Note: Version bump only for package @spectrum-web-components/table

0.48.1 (2024-10-01) #

Note: Version bump only for package @spectrum-web-components/table

0.48.0 (2024-09-17) #

Note: Version bump only for package @spectrum-web-components/table

0.47.2 (2024-09-03) #

Note: Version bump only for package @spectrum-web-components/table

0.47.1 (2024-08-27) #

Note: Version bump only for package @spectrum-web-components/table

0.47.0 (2024-08-20) #

Note: Version bump only for package @spectrum-web-components/table

0.46.0 (2024-08-08) #

Note: Version bump only for package @spectrum-web-components/table

0.45.0 (2024-07-30) #

Note: Version bump only for package @spectrum-web-components/table

0.44.0 (2024-07-15) #

Bug Fixes #

add keyboard handlers to sp-table-cell-head (#4473) (794263e)

0.43.0 (2024-06-11) #

Note: Version bump only for package @spectrum-web-components/table

0.42.5 (2024-05-24) #

Note: Version bump only for package @spectrum-web-components/table

0.42.4 (2024-05-14) #

Note: Version bump only for package @spectrum-web-components/table

0.42.3 (2024-05-01) #

Note: Version bump only for package @spectrum-web-components/table

0.42.2 (2024-04-03) #

Note: Version bump only for package @spectrum-web-components/table

0.42.1 (2024-04-02) #

Bug Fixes #

table: Add aria-rowcount to virtualized tables (#4156) (b4136ab)

0.42.0 (2024-03-19) #

Features #

asset: use core tokens (99e76f4)

0.41.2 (2024-03-05) #

Note: Version bump only for package @spectrum-web-components/table

0.41.1 (2024-02-22) #

Note: Version bump only for package @spectrum-web-components/table

0.41.0 (2024-02-13) #

Note: Version bump only for package @spectrum-web-components/table

0.40.5 (2024-02-05) #

Note: Version bump only for package @spectrum-web-components/table

0.40.4 (2024-01-29) #

Note: Version bump only for package @spectrum-web-components/table

0.40.3 (2024-01-11) #

Note: Version bump only for package @spectrum-web-components/table

0.40.2 (2023-12-18) #

Note: Version bump only for package @spectrum-web-components/table

0.40.1 (2023-12-05) #

Note: Version bump only for package @spectrum-web-components/table

0.40.0 (2023-11-16) #

Note: Version bump only for package @spectrum-web-components/table

0.39.4 (2023-11-02) #

Bug Fixes #

table: update row selection aria (6c8c706)

0.39.3 (2023-10-18) #

Note: Version bump only for package @spectrum-web-components/table

0.39.2 (2023-10-13) #

Note: Version bump only for package @spectrum-web-components/table

0.39.1 (2023-10-06) #

Note: Version bump only for package @spectrum-web-components/table

0.39.0 (2023-09-25) #

Features #

table: migrate to core tokens (#3441) (b866bab)

0.38.0 (2023-09-05) #

Note: Version bump only for package @spectrum-web-components/table

0.37.0 (2023-08-18) #

Note: Version bump only for package @spectrum-web-components/table

0.36.0 (2023-08-18) #

Note: Version bump only for package @spectrum-web-components/table

0.35.0 (2023-07-31) #

Note: Version bump only for package @spectrum-web-components/table

0.34.0 (2023-07-11) #

Bug Fixes #

table: include all dependencies, @lit-labs/observers was missing (98d0370)

0.33.2 (2023-06-14) #

Note: Version bump only for package @spectrum-web-components/table

0.33.0 (2023-06-08) #

Note: Version bump only for package @spectrum-web-components/table

0.32.0 (2023-06-01) #

Note: Version bump only for package @spectrum-web-components/table

0.31.0 (2023-05-17) #

Note: Version bump only for package @spectrum-web-components/table

0.30.0 (2023-05-03) #

Bug Fixes #

add missing "elements.js" export for sp-table component (ab8e2a7)
prevent runaway event listeners by not rendering while disconnected (aa8e8b2)
table: add resize controller to TableBody for a11y reasons (85dd406)
table: allow "change" events from table row content (97699a0)
table: allow tablebody to be resized via flex-grow (f797202)
table: update element tag in sp table sub components (4e94d70)
table: update sp-table import in elements.js (0cfe25a)
update timing to support non-virtualized rows (11ff752)

Features #

select row when clicking row (294523c)
shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)

0.1.14 (2023-04-24) #

Note: Version bump only for package @spectrum-web-components/table

0.1.13 (2023-04-05) #

Note: Version bump only for package @spectrum-web-components/table

0.1.12 (2023-03-22) #

Bug Fixes #

table: allow "change" events from table row content (97699a0)

0.1.11 (2023-03-08) #

Note: Version bump only for package @spectrum-web-components/table

0.1.10 (2023-02-23) #

Note: Version bump only for package @spectrum-web-components/table

0.1.9 (2023-02-08) #

Bug Fixes #

table: allow tablebody to be resized via flex-grow (f797202)
table: update element tag in sp table sub components (4e94d70)
table: update sp-table import in elements.js (0cfe25a)

0.1.8 (2023-01-23) #

Note: Version bump only for package @spectrum-web-components/table

0.1.7 (2023-01-09) #

Bug Fixes #

add missing "elements.js" export for sp-table component (ab8e2a7)

0.1.6 (2022-12-08) #

Note: Version bump only for package @spectrum-web-components/table

0.1.5 (2022-11-21) #

Note: Version bump only for package @spectrum-web-components/table

0.1.4 (2022-11-14) #

Note: Version bump only for package @spectrum-web-components/table

0.1.3 (2022-10-28) #

Note: Version bump only for package @spectrum-web-components/table

0.1.2 (2022-10-17) #

Note: Version bump only for package @spectrum-web-components/table

0.1.1 (2022-10-10) #

Note: Version bump only for package @spectrum-web-components/table

0.1.0 (2022-09-14) #

Bug Fixes #

update timing to support non-virtualized rows (11ff752)
table: add resize controller to TableBody for a11y reasons (85dd406)
prevent runaway event listeners by not rendering while disconnected (aa8e8b2)

Features #

select row when clicking row (294523c)

Description #

An <sp-table> is used to create a container for displaying information. It allows users to sort, compare, and take action on large amounts of data.

Usage #

yarn add @spectrum-web-components/table

Import the side effectful registration of <sp-table>, <sp-table-body>, <sp-table-cell>, <sp-table-checkbox-cell>, <sp-table-head>, <sp-table-head-cell>. and <sp-table-row> via:

import '@spectrum-web-components/table/elements.js';

Or individually via:

import '@spectrum-web-components/table/sp-table.js';
import '@spectrum-web-components/table/sp-table-body.js';
import '@spectrum-web-components/table/sp-table-cell.js';
import '@spectrum-web-components/table/sp-table-checkbox-cell.js';
import '@spectrum-web-components/table/sp-table-head.js';
import '@spectrum-web-components/table/sp-table-head-cell.js';
import '@spectrum-web-components/table/sp-table-row.js';

When looking to leverage the Table, TableBody, TableCell, TableCheckboxCell, TableHead, TableHeadCell, or TableRow base classes as a type and/or for extension purposes, do so via:

import {
    Table,
    TableBody,
    TableCell,
    TableCheckboxCell,
    TableHead,
    TableHeadCell,
    TableRow
} from '@spectrum-web-components/table';

Example #

<sp-table>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
        <sp-table-row>
            <sp-table-cell>Row Item Delta</sp-table-cell>
            <sp-table-cell>Row Item Delta</sp-table-cell>
            <sp-table-cell>Row Item Delta</sp-table-cell>
        </sp-table-row>
        <sp-table-row>
            <sp-table-cell>Row Item Echo</sp-table-cell>
            <sp-table-cell>Row Item Echo</sp-table-cell>
            <sp-table-cell>Row Item Echo</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Selection #

To manage selection on an <sp-table>, utilise the selects attribute on <sp-table>. Each <sp-table-row> has a value attribute which, by default, corresponds to its index in the table, and these values tell <sp-table> which <sp-table-row>s are selected. The selected items can be manually applied via the selected property on the table.

`selects="single"` #

When selects="single", the <sp-table> will manage a single selection in the array value of selected.

<sp-table
    selects="single"
    selected='["row1"]'
    onchange="spAlert(this, `Selected: ${JSON.stringify(this.selected)}`)"
>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row4">
            <sp-table-cell>Row Item Delta</sp-table-cell>
            <sp-table-cell>Row Item Delta</sp-table-cell>
            <sp-table-cell>Row Item Delta</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row5">
            <sp-table-cell>Row Item Echo</sp-table-cell>
            <sp-table-cell>Row Item Echo</sp-table-cell>
            <sp-table-cell>Row Item Echo</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

`selects="multiple"` #

When selects="multiple", the <sp-table> manages selections via a presence toggle and adds them to the selected array. Additionally, an <sp-table-checkbox-cell> will be made available in the <sp-table-head> in order to select/deselect all items in the <sp-table>.

<sp-table
    selects="multiple"
    selected='["row1", "row2"]'
    onchange="spAlert(this, `Selected: ${JSON.stringify(this.selected)}`)"
>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row4">
            <sp-table-cell>Row Item Delta</sp-table-cell>
            <sp-table-cell>Row Item Delta</sp-table-cell>
            <sp-table-cell>Row Item Delta</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row5">
            <sp-table-cell>Row Item Echo</sp-table-cell>
            <sp-table-cell>Row Item Echo</sp-table-cell>
            <sp-table-cell>Row Item Echo</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Emphasized #

Use the emphasized attribute to add priority to the information that is delivered within your <table> element. In particular, this affects the appearance of selected rows, and will set the emphasized style for the checkboxes within sp-table-checkbox-cell. Leaving off the emphasized attribute will display the non-emphasized colors.

<sp-table emphasized selects="multiple" selected='["row1"]'>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Density #

The optional density property changes the spacing around table cell content from the "regular" default. It accepts the values of compact or spacious.

Compact

<sp-table density="compact">
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Spacious

<sp-table density="spacious">
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Sizes #

Small

<sp-table size="s">
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Medium (Default)

<sp-table>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Large

<sp-table size="l">
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Extra Large

<sp-table size="xl">
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Quiet #

When using the quiet property, the overall look of the table will change. The quiet variant of Table has a transparent background and no borders on the left and right.

<sp-table quiet>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
    <sp-table-body>
        <sp-table-row value="row1">
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
            <sp-table-cell>Row Item Alpha</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row2">
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
            <sp-table-cell>Row Item Bravo</sp-table-cell>
        </sp-table-row>
        <sp-table-row value="row3">
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
            <sp-table-cell>Row Item Charlie</sp-table-cell>
        </sp-table-row>
    </sp-table-body>
</sp-table>

Virtualized Table #

For large amounts of data, the <sp-table> can be virtualised to easily add table rows by using properties.

<sp-table
    id="table-virtualized-demo"
    style="height: 200px"
    scroller="true"
>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
</sp-table>
<script type="module">
    const initItems = (count) => {
        const total = count;
        const items = [];
        while (count) {
            count--;
            items.push({
                name: String(total - count),
                date: count,
            });
        }
        return items;
    };
    const initTable = () => {
        const table = document.querySelector('#table-virtualized-demo');
        table.items = initItems(50);

        table.renderItem = (item, index) => {
            const cell1 = document.createElement('sp-table-cell');
            const cell2 = document.createElement('sp-table-cell');
            const cell3 = document.createElement('sp-table-cell');
            cell1.textContent = `Row Item Alpha ${item.name}`;
            cell2.textContent = `Row Item Alpha ${index}`;
            cell3.textContent = `Last Thing`;
            return [cell1, cell2, cell3];
        }
    };
    customElements.whenDefined('sp-table').then(() => {
        initTable();
    });
</script>

How to use it #

The virtualised table takes items as either a property or a JSON-encoded string, an array of type Record, where the key is a string and the value can be whatever you'd like. items is then fed into the renderItem method, which takes an item and its index as parameters and renders the <sp-table-row> for each item. An example is as follows:

const renderItem = (item: Item, index: number): TemplateResult => {
    return html`
        <sp-table-cell>Rowsaa Item Alpha ${item.name}</sp-table-cell>
        <sp-table-cell>Row Item Alpha ${item.date}</sp-table-cell>
        <sp-table-cell>Row Item Alpha ${index}</sp-table-cell>
    `;
};

renderItem is then included as a property of <sp-table>, along with the items, to render a full <sp-table> without excessive manual HTML writing.

You can also render a different cell at a particular index by doing something like below:

const renderItem = (item: Item, index: number): TemplateResult => {
    if (index === 15) {
        return html`
            <sp-table-cell style="text-align: center">Custom Row</sp-table-cell>
        `;
    }
    return html`
        <sp-table-cell>Row Item ${item.name}</sp-table-cell>
        <sp-table-cell>Row Item ${item.date}</sp-table-cell>
        <sp-table-cell>Row Item ${index}</sp-table-cell>
    `;
};

Please note that there is a bug when attempting to select all virtualised elements. The items are selected programatically, it's just not reflected visually.

Selection #

By default the selected property will surface an array of item indexes that are currently selected. However, when making a selection on a virtualized table, it can be useful to track selection as something other than indexes. To do so, set a custom method for the itemValue property. The itemValue method accepts an item and its index as arguments and should return the value you would like to track in the selected property.

<sp-table
    id="table-item-value-demo"
    style="height: 200px"
    scroller="true"
    selects="multiple"
>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
</sp-table>
<div class="selection">Selected: [ ]</div>
<script type="module">
    const initItems = (count) => {
        const total = count;
        const items = [];
        while (count) {
            count--;
            items.push({
                id: crypto.randomUUID(),
                name: String(total - count),
                date: count,
            });
        }
        return items;
    };
    const initTable = () => {
        const table = document.querySelector('#table-item-value-demo');
        table.items = initItems(50);

        table.renderItem = (item, index) => {
            const cell1 = document.createElement('sp-table-cell');
            const cell2 = document.createElement('sp-table-cell');
            const cell3 = document.createElement('sp-table-cell');
            cell1.textContent = `Row Item Alpha ${item.name}`;
            cell2.textContent = `Row Item Alpha ${index}`;
            cell3.textContent = `Last Thing`;
            return [cell1, cell2, cell3];
        };

        table.addEventListener('change', (event) => {
            const selected = event.target.nextElementSibling;
            selected.textContent = `Selected: ${JSON.stringify(event.target.selected, null, ' ')}`;
        });
    };
    customElements.whenDefined('sp-table').then(() => {
        initTable();
    });
</script>

Row Types #

All values in the item array are assumed to be homogenous by default. This means all of the rendered rows are either delivered as provided, or, in the case you are leveraging selects, rendered with an <sp-table-checkbox-cell>. However, when virtualizing a table with selection, it can sometimes be useful to surface rows with additional interactions, e.g. "Load more data" links. To support that, you can optionally include the _$rowType$ brand in your item. The values for this are outlined by the RowType enum and include ITEM (0) and INFORMATION (1). When _$rowType$: RowType.INFORMATION is provided, it instructs the <sp-table> not to deliver an <sp-table-checkbox-cell> in that row.

<sp-table
    id="table-row-type-demo"
    style="height: 200px"
    scroller="true"
    selects="single"
>
    <sp-table-head>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
        <sp-table-head-cell>Column Title</sp-table-head-cell>
    </sp-table-head>
</sp-table>
<script type="module">
    const initItems = (count) => {
        const total = count;
        const items = [];
        while (count) {
            count--;
            items.push({
                name: String(total - count),
                date: count,
            });
        }
        return items;
    };
    const initTable = () => {
        const table = document.querySelector('#table-row-type-demo');
        const items = initItems(50);
        items.splice(3, 0, {
            _$rowType$: 1,
        });
        table.items = items;

        table.renderItem = (item, index) => {
            if (item._$rowType$ === 1) {
                const infoCell = document.createElement('sp-table-cell');
                infoCell.textContent = 'Use this row type for non-selectable content.';
                return [infoCell];
            }
            const cell1 = document.createElement('sp-table-cell');
            const cell2 = document.createElement('sp-table-cell');
            const cell3 = document.createElement('sp-table-cell');
            cell1.textContent = `Row Item Alpha ${item.name}`;
            cell2.textContent = `Row Item Alpha ${index}`;
            cell3.textContent = `Last Thing`;
            return [cell1, cell2, cell3];
        };
    };
    customElements.whenDefined('sp-table').then(() => {
        initTable();
    });
</script>

The `scroller` property #

By default, the virtualized table doesn't contain a scroll bar and will display the entire length of the table body. Use the scroller property and specify an inline style for the height to get a Table of your desired height that scrolls.

Sorting on the Virtualized Table #

The virtualized table supports sorting its elements.

For each table column you want to sort, use the sortable attribute in its respective <sp-table-head-cell>. sort-direction="asc"|"desc" specifies the direction the sort goes, in either ascending or descending order, respectively. The @sorted event listener on <sp-table> can be utilised to specify a method to fire when the <sp-table-head-cell> dispatches the sorted event. To specify which aspect of an item you'd like to sort by, use the sort-key attribute.

<sp-table
    id="sorted-virtualized-table"
    style="height: 200px"
    scroller="true"
>
    <sp-table-head>
        <sp-table-head-cell sortable sort-direction="desc" sort-key="name">
            Sortable Column
        </sp-table-head-cell>
        <sp-table-head-cell>Non-sortable Column</sp-table-head-cell>
        <sp-table-head-cell>Non-sortable Column</sp-table-head-cell>
    </sp-table-head>
</sp-table>
<script type="module">
    const initItems = (count) => {
        const total = count;
        const items = [];
        while (count) {
            count--;
            items.push({
                name: String(total - count),
                date: count,
            });
        }
        return items;
    }

    let items = initItems(50);

    const initTable = () => {
        const table = document.querySelector('#sorted-virtualized-table');

        table.items = items;

        table.renderItem = (item, index) => {
            const cell1 = document.createElement('sp-table-cell');
            const cell2 = document.createElement('sp-table-cell');
            const cell3 = document.createElement('sp-table-cell');
            cell1.textContent = `Row Item Alpha ${item.name}`;
            cell2.textContent = `Row Item Beta ${item.date}`;
            cell3.textContent = `Index: ${index}`;
            return [cell1, cell2, cell3];
        }
        table.addEventListener('sorted', (event) => {
            const { sortDirection, sortKey } = event.detail;
            items = items.sort((a, b) => {
                const first = String(a[sortKey]);
                const second = String(b[sortKey]);
                return sortDirection === 'asc'
                    ? first.localeCompare(second)
                    : second.localeCompare(first);
            });
            table.items = [...items];
        });
    };

    customElements.whenDefined('sp-table').then(() => {
        initTable();
    });
</script>

Spectrum Web Components

sp-table

NPM

1.0.0

Storybook

View Storybook

Attributes and Properties #

Events #

1.0.0 (2024-10-31) #

0.49.0 (2024-10-15) #

0.48.1 (2024-10-01) #

0.48.0 (2024-09-17) #

0.47.2 (2024-09-03) #

0.47.1 (2024-08-27) #

0.47.0 (2024-08-20) #

0.46.0 (2024-08-08) #

0.45.0 (2024-07-30) #

0.44.0 (2024-07-15) #

Bug Fixes #

0.43.0 (2024-06-11) #

0.42.5 (2024-05-24) #

0.42.4 (2024-05-14) #

0.42.3 (2024-05-01) #

0.42.2 (2024-04-03) #

0.42.1 (2024-04-02) #

Bug Fixes #

0.42.0 (2024-03-19) #

Features #

0.41.2 (2024-03-05) #

0.41.1 (2024-02-22) #

0.41.0 (2024-02-13) #

0.40.5 (2024-02-05) #

0.40.4 (2024-01-29) #

0.40.3 (2024-01-11) #

0.40.2 (2023-12-18) #

0.40.1 (2023-12-05) #

0.40.0 (2023-11-16) #

0.39.4 (2023-11-02) #

Bug Fixes #

0.39.3 (2023-10-18) #

0.39.2 (2023-10-13) #

0.39.1 (2023-10-06) #

0.39.0 (2023-09-25) #

Features #

0.38.0 (2023-09-05) #

0.37.0 (2023-08-18) #

0.36.0 (2023-08-18) #

0.35.0 (2023-07-31) #

0.34.0 (2023-07-11) #

Bug Fixes #

0.33.2 (2023-06-14) #

0.33.0 (2023-06-08) #

0.32.0 (2023-06-01) #

0.31.0 (2023-05-17) #

0.30.0 (2023-05-03) #

Bug Fixes #

Features #

0.1.14 (2023-04-24) #

0.1.13 (2023-04-05) #

0.1.12 (2023-03-22) #

Bug Fixes #

0.1.11 (2023-03-08) #

0.1.10 (2023-02-23) #

0.1.9 (2023-02-08) #

Bug Fixes #

0.1.8 (2023-01-23) #

0.1.7 (2023-01-09) #

Bug Fixes #

0.1.6 (2022-12-08) #

0.1.5 (2022-11-21) #

0.1.4 (2022-11-14) #

0.1.3 (2022-10-28) #

0.1.2 (2022-10-17) #

0.1.1 (2022-10-10) #

0.1.0 (2022-09-14) #

Bug Fixes #

Features #

Description #

Usage #

Example #

Spectrum
Web Components

`selects="single"` #

`selects="multiple"` #

The `scroller` property #