Magic Table is a custom element that adds interactivity to an HTML table. The goal of the element is to enhance the functionality of the table progressively, making as few changes to the DOM and styles as possible.
Magic Table supports sticky headers and sorting based on column values. Details for each feature can be found in the Usage section below.
To use Magic Table in a javascript project, install magic-table from NPM.
npm install @dpk2442/magic-tableThis package exports the MagicTable class, which is a custom element. Typically this should be registered in
window.customElements as follows:
import { MagicTable } from 'magic-table';
window.customElements.define('magic-table', MagicTable);Magic Table also ships with a script, magic-table.js, that will automatically load and register the custom element.
There are three ways to use this script:
- Download it from the latest release.
- Install the NPM package, as listed in the previous section, and then copy it from the
distfolder. - Directly include it from a CDN. jsDelivr can serve files directly from NPM, and you can find
magic-tablehere: https://www.jsdelivr.com/package/npm/@dpk2442/magic-table.
However you fetch the script, once including it in your page it will make the <magic-table> tag available for use.
<!DOCTYPE html>
<html>
<head>
<title>Test magic-table</title>
<script src="magic-table.js" defer></script>
</head>
<body>
<magic-table sticky-header>
<table>
<thead>
<tr>
<th>Column 1</th>
<th>Column 2</th>
</tr>
</thead>
<tbody>
<tr>
<td>Cell 1</td>
<td>Cell 2</td>
</tr>
</tbody>
</table>
</magic-table>
</body>
</html>When magic-table initializes, it will add the mt-activated class to itself. Individual features of the element are
enabled through attributes, and are documented below.
Sticky headers can be enabled with the sticky-header attribute. The table must contain a thead element, which will
receive the class mt-sticky-header when sticky headers are enabled.
<magic-table sticky-header>
<table>
<thead class="mt-sticky-header">
...
</thead>
<tbody>
...
</tbody>
</table>
</magic-table>Overflow classes can be enabled with the overflow-classes attribute. When enabled the magic-table will receive the
following classes if the table is overflowing:
mt-overflow-top: More table can be seen by scrolling up.mt-overflow-bottom: More table can be seen by scrolling down.mt-overflow-left: More table can be seen by scrolling left.mt-overflow-right: More table can be seen by scrolling right.
Important
These classes are only recalculated on scroll events, so toggling the overflow state can have unintended side effects.
Sorting can be enabled with the sortable attribute. The header (th) of each sortable column should have a
data-mt-sortable attribute set to the sorting type to be used, and the header will have the mt-sortable class added
to it if sorting is enabled for that column.
<magic-table sortable>
<table>
<thead>
<tr>
<th>Column 1</th>
<th data-mt-sortable="string" class="mt-sortable">Column 2</th>
</tr>
</thead>
<tbody>
...
</tbody>
</table>
</magic-table>| Type | Details |
|---|---|
date |
This sort type will treat the values in the column as Date objects, using new
Date(columnValue) to construct an instance to be used for sorting.
|
string |
This sort will perform simple alphabetic sorting on the values in the column. |
natural |
This sort will perform "natural" sorting, treating numerical values as numbers. |
number |
This sort treats each value as a number, using parseFloat to convert the value.
|
custom |
This sort allows using a custom function to sort the data in the column. The function name should be
specified as custom:functionName, and the columns values will be passed as strings. The
function should follow the definition of the compareFn that can be passed to Array.prototype.sort().
|
When a column is sorted, the class mt-sorted-asc or mt-sorted-desc will be set on the column that is sorted,
depending on the order. All other columns will have neither of these classes set.
The table can be sorted by calling the API on a reference to the magic-table element.
| Type | Details |
|---|---|
sortByColumn(indexOrId[, order]) |
Sorts the table by the given column. The columns are indexed from 0, or can be referred to by using the value set in the `id` attribute. The second parameter controls sort order and can be set to `asc` or `desc`; if ommitted the sort order will be toggled, starting with `asc` if the table is not currently sorted by that column. |
clearSort() |
Clears the sorting of the table and resets it to the page load order. |
currentSortInfo |
This property returns null if the table is in the default sorting order, or the current sorting info (see events section below) if the table is currently sorted. |
When the table is sorted, a CustomEvent of type mtsorted will be published on the magic-table. When the sort is
cleared, a CustomEvent of type mtsortcleared is published. The detail field of the mtsorted event has the
following schema, which is also what is returned from the currentSortInfo property mentioned above.
interface MagicTableSortInfo {
columnIndex: number;
header: HTMLTableCellElement;
sortOrder: SortOrder;
}Any button element placed inside a sortable column header's th element can be given the data-mt-sort attribute to
automatically have an event handler attached to trigger a sort of that column. The attribute can have no value, in which
case the button will toggle the sort, or it can be set to asc or desc to force the sort in that order.
<magic-table sortable>
<table>
<thead>
<tr>
<th>Column 1</th>
<th data-mt-sortable="string" class="mt-sortable">
<button data-mt-sort>Column 2</button>
</th>
</tr>
</thead>
<tbody>
...
</tbody>
</table>
</magic-table>