A web component to enable users to sort table data by clicking on column headers. Built with accessibility in mind, featuring keyboard navigation, screen reader announcements, and light DOM manipulation.
Based on the original jquery.easy-sortable-tables.js by Aaron Gustafson.
- ✅ Accessible: Full keyboard navigation support with Enter/Space activation
- ✅ Screen Reader Friendly: Announces sort changes via ARIA live regions
- ✅ Light DOM: No Shadow DOM - works with your existing table markup
- ✅ Flexible Sorting: Supports text, numeric, and custom sort keys
- ✅ Grouped Tables: Maintains grouped
tbodyelements when sorting - ✅ No Dependencies: Pure vanilla JavaScript web component
- ✅ Small Footprint: Lightweight and performant
npm install @aarongustafson/table-sortableTypeScript ready
The package ships with
table-sortable.d.ts. Importing either the class ({ TableSortableElement }) or the guarded definition helper automatically provides typed event payloads (table-sortable:sort) and reflective properties (labelSortable,labelAscending,labelDescending).
Import the class and define the custom element with your preferred tag name:
import { TableSortableElement } from '@aarongustafson/table-sortable';
customElements.define('my-custom-name', TableSortableElement);Use the guarded definition helper to register the element when customElements is available:
import '@aarongustafson/table-sortable/define.js';If you prefer to control when the element is registered, call the helper directly:
import { defineTableSortable } from '@aarongustafson/table-sortable/define.js';
defineTableSortable();You can also include the guarded script from HTML:
<script src="./node_modules/@aarongustafson/table-sortable/define.js" type="module"></script>Wrap your existing table in a <table-sortable> element. The component uses progressive enhancement - it will automatically inject sortable buttons into table headers:
<table-sortable>
<table>
<thead>
<tr>
<th>Name</th>
<th>Age</th>
<th>City</th>
</tr>
</thead>
<tbody>
<tr>
<td>Charlie</td>
<td>35</td>
<td>New York</td>
</tr>
<tr>
<td>Alice</td>
<td>28</td>
<td>Boston</td>
</tr>
<tr>
<td>Bob</td>
<td>42</td>
<td>Chicago</td>
</tr>
</tbody>
</table>
</table-sortable>The component uses pure progressive enhancement - it automatically creates accessible <button> elements inside each <th> for sorting. You don't need to add any buttons or links manually.
Use the data-sort-value attribute to specify a custom value to sort by, different from the displayed content:
<table-sortable>
<table>
<thead>
<tr>
<th>Product</th>
<th>Price</th>
</tr>
</thead>
<tbody>
<tr>
<td data-sort-value="WIDGET-B">Widget B (Premium)</td>
<td data-sort-value="50">$50.00</td>
</tr>
<tr>
<td data-sort-value="WIDGET-A">Widget A (Basic)</td>
<td data-sort-value="30">$30.00</td>
</tr>
</tbody>
</table>
</table-sortable>This is useful for:
- Sorting formatted numbers (currency, percentages)
- Sorting dates by ISO format while displaying a friendly format
- Custom sorting logic (e.g., priority: High > Medium > Low)
Hidden Sort Keys
Use an element with the class [data-sort-as] to provide a hidden sort value:
<table-sortable>
<table>
<thead>
<tr>
<th>Full Name</th>
</tr>
</thead>
<tbody>
<tr>
<td><span data-sort-as>SMITH</span>John Smith</td>
</tr>
<tr>
<td><span data-sort-as>ANDERSON</span>Emily Anderson</td>
</tr>
</tbody>
</table>
</table-sortable>The [data-sort-as] element should be hidden with CSS:
[data-sort-as] {
display: none;
}This allows sorting by last name while displaying "First Last" format.
To maintain groupings while sorting, use multiple <tbody> elements with data-table-sort-group attributes:
<table-sortable>
<table>
<thead>
<tr>
<th>Name</th>
<th>Score</th>
</tr>
</thead>
<tbody>
<tr data-table-sort-group="engineering">
<td>Charlie (Engineering)</td>
<td>85</td>
</tr>
</tbody>
<tbody>
<tr data-table-sort-group="design">
<td>Alice (Design)</td>
<td>92</td>
</tr>
</tbody>
<tbody>
<tr data-table-sort-group="sales">
<td>Bob (Sales)</td>
<td>78</td>
</tr>
</tbody>
</table>
</table-sortable>Each group (tbody) will be sorted independently and maintain its structure.
The component fires custom events that you can listen to:
| Event | Description | Detail |
|---|---|---|
table-sortable:sort |
Fired when a column is sorted | { column: number, direction: 'asc'|'desc', header: HTMLElement } |
const element = document.querySelector('table-sortable');
element.addEventListener('table-sortable:sort', (event) => {
const { column, direction, header } = event.detail;
console.log(`Sorted column ${column} (${header.textContent}) in ${direction}ending order`);
});The component supports attributes for customizing screen reader announcements:
| Attribute | Description | Default |
|---|---|---|
label-sortable |
Label for unsorted columns | "Click to sort" |
label-ascending |
Label when sorted ascending | "sorted ascending. Click to sort descending" |
label-descending |
Label when sorted descending | "sorted descending. Click to sort ascending" |
<table-sortable
label-sortable="Cliquez pour trier"
label-ascending="trié croissant. Cliquez pour trier décroissant"
label-descending="trié décroissant. Cliquez pour trier croissant">
<table>
<!-- table content -->
</table>
</table-sortable>The component uses light DOM, so you can style the table normally with CSS. The component adds these classes to help style sort indicators:
| Class | Applied To | Description |
|---|---|---|
active |
<th> |
The currently sorted column |
up |
<th> |
Column sorted in ascending order |
down |
<th> |
Column sorted in descending order |
sorted |
<col> |
The currently sorted column (for column styling) |
The component supports CSS custom properties for visual indicators:
| Property | Description | Default |
|----------|-------------|---------||
| --table-sortable-indicator-asc | Ascending sort indicator | ↑ |
| --table-sortable-indicator-desc | Descending sort indicator | ↓ |
/* Customize sort indicators */
table-sortable {
--table-sortable-indicator-asc: '▲';
--table-sortable-indicator-desc: '▼';
}
/* Style active column header */
thead th.active {
background-color: #e3f2fd;
}
/* Highlight sorted column */
col.sorted {
background-color: rgba(0, 102, 204, 0.05);
}The component is built with accessibility as a priority:
-
Keyboard Navigation:
- All sortable headers are focusable with Tab
- Activate sorting with
EnterorSpacekeys
-
Screen Reader Support:
aria-sortattribute indicates column sort state (ascending, descending, none)- Live region announces sort changes using customizable labels
- Updates are announced politely without interrupting
-
Progressive Enhancement:
- Automatically creates accessible buttons if none are provided
- Works with existing links or buttons in markup
-
Visual Indicators:
- CSS classes indicate active column and sort direction
- Focus indicators for keyboard navigation
- Column highlighting via
<col>elements
The component automatically injects <colgroup> and <col> elements if they don't exist, allowing you to style entire columns. The currently sorted column receives a .sorted class on its corresponding <col> element.
- First click: Sort ascending
- Second click: Sort descending
- Text sorting: Case-insensitive alphabetical
- Numeric sorting: Automatic detection and numeric comparison
- Mixed content: Text values sort before or after numbers depending on direction
The component automatically detects numeric values and sorts them numerically rather than alphabetically (so 100 comes after 20, not after 1).
This component uses modern web standards:
- Custom Elements v1
- ES Modules
- ES6+ JavaScript features
Supported Browsers:
- Chrome/Edge 88+
- Firefox 87+
- Safari 14+
For older browsers, you may need polyfills from @webcomponents/webcomponentsjs.
# Install dependencies
npm install
# Run tests
npm test
# Run tests with UI
npm run test:ui
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Format code
npm run format
# View demo locally
open demo/index.htmlMIT © Aaron Gustafson
Based on jquery.easy-sortable-tables.js © Aaron Gustafson