data-table
Sortable, filterable tables from plain custom tags — one behavior owner
(<data-table> + <data-th>), everything else is CSS.
Features
- Sort Click a
<data-th>to visually sort by string, number, or date - Filter
filter-valuehides non-matching rows - Export The
--exportcommand downloads visible / all rows as CSV / JSON - DOM-stable Sort / filter via CSS only. Does not conflict with DOM owners, such as Quark.
- Bindable counts
.provisionis{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue }— a "12 of 40 rows" readout is one Quark rule - Plain structural tags
<data-thead>/<data-tbody>/<data-tr>/<data-td>are CSS-only — no registration cost
Installation
This package is available in the
<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/data-table@0.1.5/dist/index.umd.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@excom/data-table@0.1.5/dist/index.css">npm install @excom/data-table<!-- import path to `node_modules` will depend on your build setup -->
<script type="module" src="/node_modules/@excom/data-table"></script>
<link rel="stylesheet" href="/node_modules/@excom/data-table">import "@excom/data-table";@import "@excom/data-table/index.css";Peer dependencies (0)
Packages a consumer must install alongside this one. Workspace deps are bundled.
| Package | Version |
|---|---|
|
Usage
Only <data-table> and <data-th> are registered custom elements.
<data-thead>, <data-tbody>, <data-tr>, <data-td>, <data-tfoot>, and <data-tf> are plain tags — this package's CSS styles them as a table (or apply the equivalent .tag-data-* classes).
Sort and filter are visual only (CSS order / display).
Row nodes never move or leave the DOM, so Quark bindings and iterate() tables keep working.
<data-table>
<data-thead>
<data-tr>
<data-th column-type="string" sort-direction="asc">Name</data-th>
<data-th column-type="number">Age</data-th>
</data-tr>
</data-thead>
<data-tbody>
<data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>
<data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>
</data-tbody>
</data-table><data-table>
<data-thead>
<data-tr>
<data-th column-type="string" sort-direction="asc">Name</data-th>
<data-th column-type="number">Age</data-th>
</data-tr>
</data-thead>
<data-tbody>
<data-tr><data-td>Adam</data-td><data-td>36</data-td></data-tr>
<data-tr><data-td>Beau</data-td><data-td>29</data-td></data-tr>
</data-tbody>
</data-table><data-tbody> is required — sorting and filtering both operate on its
<data-tr> children.
.provision reports the row counts and the active sort / filter, recomputed after connect, after a sort, and after every filter change.
Read it from a rule matching the table:
data-table {
$visible: prop("provision").visibleRows;
$total: prop("provision").totalRows;
[bind-count] { content: "#{$visible} of #{$total} rows"; }
}data-table {
$visible: prop("provision").visibleRows;
$total: prop("provision").totalRows;
[bind-count] { content: "#{$visible} of #{$total} rows"; }
}API Reference
Attributes
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
Provision
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements
Child or descendant elements are recognized by and relevant to its functionality.Styles
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
data-table
Attributes (2)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
filter-casing
Match
filter-value case-sensitively instead of the default case-insensitive comparison.
filterCasing
boolean
falsefilter-value
Hides
data-tr rows (via --data-tr-display: none) whose text content doesn't include this value. Case-insensitive unless filter-casing is set. Unset / empty clears the filter. Rows stay in the DOM so Quark bindings survive.
filterValue
string
nullProvision (1)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
provision
{ totalRows, visibleRows, sortColumnIndex, sortDirection, filterValue } — recomputed after connect, after the data-table-sort default action, and after every filter change. Not reflected as an attribute.
provision
DataTableProvision
Events (3)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
data-table-sort
Cancelable. Dispatched when the active sort column / direction changes: on connect (if a
data-th already has sort-direction) and after every data-th-sort. Call preventDefault() to take over sorting yourself.
Type
DataTableSortEvent
event.detail.rows by columnIndex with sortFn and sets --data-tr-order on each row (visual CSS order — DOM order is unchanged).data-th-sortDataThSortEvent
data-th when its sort-direction changes. Sets that header as the active sort column (clearing sort-direction from the previously active one) and emits data-table-sort.
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
--exportdata-tr / data-td / data-th text content and downloads it. Options are data-* on the invoker: data-file-type (csv, the default, or json), data-file-name (default export_table_<locale-date>), and data-full to download every row in DOM order instead of only the visible rows in visual sort order. Filtering needs no command: write filter-value / filter-casing.
Recognized Elements (4)
Child or descendant elements are recognized by data-table and relevant to its functionality.
Required row container. Sorting and filtering both operate on its
data-tr children.
Cell within a
data-tr, read as sortable / export cell content.
Sortable column header. Clicking toggles its
sort-direction and fires data-th-sort, which becomes the active column.
Row, direct child of
data-tbody. Gets --data-tr-order on sort and --data-tr-display on filter. DOM order is unchanged.
Styles (8)
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
--data-table-cols<integer>1@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
:--data-tabledata-table, .tag-data-table:--data-tbodydata-tbody, .tag-data-tbody:--data-tddata-td, .tag-data-td:--data-tfdata-tf, .tag-data-tf:--data-tfootdata-tfoot, .tag-data-tfoot:--data-theaddata-thead, .tag-data-thead:--data-trdata-tr, .tag-data-trdata-th
Attributes (2)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
column-type
Sort comparator to use for this column's cell values.
data-table treats null as "string".
columnType
string
"string" | "number" | "date"nullsort-direction
Current sort direction. A click toggles between
asc / desc; setting it (by any means) fires data-th-sort. Only one data-th per table should carry this at a time — the parent <data-table> clears the previously active header when a new one is set.
sortDirection
string
"asc" | "desc"nullProvision (0)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events (1)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
data-th-sort
Dispatched whenever
sort-direction is set, whether by a click or programmatically. Bubbles to the parent <data-table>.
Type
DataThSortEvent
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements (0)
Child or descendant elements are recognized by data-th and relevant to its functionality.Styles (4)
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
:--data-thdata-th, .tag-data-th:--data-th--sort:is(:--data-th):--data-th--sort-asc[sort-direction="asc"], [aria-sort="ascending"]:--data-th--sort-desc[sort-direction="desc"], [aria-sort="descending"]Release notes (1)
0.1.1
- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources
Release notes
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
Examples
Filter rows + export as CSV
Filtering is State: write filter-value / filter-casing on the table — here a Quark @on input block copies the search field into them. Matching is case-insensitive unless filter-casing is set.
Invoke --export on the table (<button command="--export" commandfor="…">) to download its visible rows (visual sort order). The button's data-file-type is csv (default) or json; data-file-name sets the download name; data-full downloads every row in DOM order, regardless of filtering / sorting.
The first export button is the happy path (the table as you see it, including active filter / sort). The form below it writes data-file-type / data-file-name / data-full onto its button.