A tiny, Vanilla/Plain JavaScript table sorter
npm install sortable-tablesort    
Makes any table with class="sortable", er, sortable. The user can click on a table header and change the sorting of the table rows.
Just include the JavaScript and it will work. No function calls are needed, everything is handled by a JavaScript HTML DOM EventListener.
🔍 searchable - A companion library that makes tables searchable/filterable, perfect to use alongside sortable!
You can find a simple demo on
- Factoids
- "Installation"
- link to jsDelivr
- copy file to assets folder
- npm package
- a use links in the html
- b import files in javascript
- Flavours/Versions
- Lightweight - default
- Full-Featured - automatic
- Test it out
- Mutation Observer and Nested Tables
- Which Version Should I Use?
- Non-sortable field
- using class="no-sort"
- using CSS
- using td instead of th
- Indicators/arrows on the left side
- NOTE ABOUT CSS/SCSS
- Sticky headers
- Sorting sizes, dates and such
- Alternative sorting
- Colspans/Sort on specific column
- Concerning rowspan
- Ascending sort
- Tiebreaker / secondary sort
- Empty/null rows always last
- Accessibility
- Sort Events
- Sort on load
- Using the default package
- Using the auto package:
- Thank you...
- 1.71K minified. (899 bytes gzipped)
- Works with JavaScript generated tables. (since we are using an eventListener)
- Lightning fast. _Huge_ tables will make it slow and may freeze the browser, especially for mobiles, so you know...
- Requires thead and tbody.
- rowspan is not supported 😢
- NOT tested with React, Angular, Vue, etc.
- Works with Svelte!
There are three ways to use sortable, all of which have their pros and cons. S Anand and dkhgh had some interesting thoughts about it.
``html`
Role
Name
Genius
Rick
Sidekick
Morty
The span on line four is just there to prove that you can have elements inside th!
⚠️ _If you are concerned about bugs, I recommend using version numbers instead of "latest"._
Same as above, but link to your own files from the dist directory
`html`
...
...
First,
`bash`
npm install sortable-tablesortyarn add sortable-tablesort
pnpm install sortable-tablesort
Now you can:
#### a) use links in the html
Same as above, with links to files from the dist directory
`html`
...
...
or
#### b) import files in javascript
`javascript`
// main.js
import 'sortable-tablesort/dist/sortable.min.css'
import 'sortable-tablesort/dist/sortable.min.js'
// OR
import 'sortable-tablesort/dist/sortable.auto.min.js'
There are two flavours, Lightweight (default) and Full-Featured (Automatic)
Lightweight is the old-school sortable with an eventListener only, where you can add the a11y package if you want. This is probably the one you are looking for.
`html`
This one includes accessibility, auto-initialization, mutation observer, and automatic sorting on load.
- Auto-sort on load: Add aria-sort="ascending" or aria-sort="descending" to any th to sort that column when the page loads.sortable
- Auto-initialization: Automatically finds and initializes all tables on page load.sortable
- Mutation observer: Automatically initializes new tables added to the HTML DOM after page load
Note: This version already includes all accessibility features - no need to load sortable.a11y.js separately.
`html`
⚠️ _The file is a bit bigger (2.72K minified / 1.22K gzipped) since there is more code, and the mutation observer triggers every time there is a change to the DOM. So if you are using React or some other library that affects the DOM a lot (it is not tested with React or any other DOM heavy libs), please be careful._
Performance note: The mutation observer watches for all DOM changes. If your application frequently modifies the DOM (e.g., real-time updates, animations), this could impact performance. Consider using the lightweight version if you:
- Have tables that update their content frequently
- Use frameworks that perform many DOM updates
- Don't need automatic initialization of dynamically added tables
#### Test it out
`html`
#### Mutation Observer and Nested Tables
Note that the observer only triggers when you add tables _directly_ to the DOM! If you wrap the table in a div for instance, you need to make sure that the div is added to the DOM _before_ the table is.
`js
const div = document.createElement('div')
// This will NOT trigger the mutation observer
div.appendChild(table) // adds the table to a div that is not part of the DOM
document.body.appendChild(div) // Now the DIV is added to the dom, not the table
// This WILL trigger the mutation observer
document.body.appendChild(div) // the div is added to the DOM, becoming part of the DOM
div.appendChild(table) // the table is added to the DOM
`
| Feature | sortable.js | sortable.js + sortable.a11y.js | sortable.auto.js |
| ------------------- | -------------------- | ------------------------------ | --------------------- |
| Basic sorting | ✓ | ✓ | ✓ |
| Size | 1.71K (899B gzipped) | ~2.7K combined | 3.04K (1.36K gzipped) |
| Accessibility | ✗ | ✓ | ✓ |
| Auto-initialization | ✗ | ✗ | ✓ |
| Mutation observer | ✗ | ✗ | ✓ |
| Auto-sort on load | ✗ | ✗ | ✓ |
| Performance impact | Minimal | Minimal | Moderate\* |
\*Due to mutation observer watching DOM changes
If you wish to disable sorting for a specific field, the easiest (and best) way is to add class="no-sort" to it, like so:
`html`
Role
Name
Sorting will not be triggered if you click on "Role".
This is a bit trickier, but it doesn't require any changes to the html, so I guess it could be worth it in some cases.
`css
/ the first column in every sortable table should not be sortable/
.sortable th:nth-child(1) {
pointer-events: none;
}
/ the seventh column in the second .sortable table should not be sortable/
.sortable:nth-of-type(2) th:nth-child(7) {
pointer-events: none;
}
`
The eventListener only triggers on th, not td, so this would disable sorting for "Role":
`html`
Role
Name
⚠️ _Since th and td are not the same thing, you would most likely still have to use CSS to make them look the way you want. (It might also mess with accessibility.) In some cases it could be worth it, but I recommend the .no-sort alternative_.
If you have text that is aligned on the right side, you may want to have the arrows on the left side.
This is solved by adding a class to the css and using ::before instead of ::after.
(You can of course use a pure css solution, without class names - just like with the non-sortable field - but _that_ I will leave for you to figure out.)
`css`
.sortable th.indicator-left::after {
content: '';
}
.sortable th.indicator-left::before {
margin-right: 3px;
content: '▸';
}
/ etc. /
The css/scss in this repo was only ever meant as an example. It was never intended to be actually _used_.
That said, if you're feeling lazy, here are two stylesheets you can use:
`html
`
I'm not sure if it's a good idea to have it in the main css, BUT if you are using the above sortable(.min).css file (not the -base files) and want sticky headers, you can simply add the class sticky to the table.
Blame razorkyle, it was his idea! 😜
`html`
...
If you are not using the css file, you can use the following css:
`css`
.sortable thead th {
position: sticky;
top: 0;
z-index: 1;
}
Using the data-sort attribute in tbody > td you can have one visible value and one sortable value. This is useful in case you have for instance sizes like kb, Mb, GB, or really weird date formats. 😉
`html`
Movie Name
Size
Release date
Zack Snyder's Justice League
900MB
03/18/2021
The Sound of Music
1.5GB
12/09/1965
If you click on a table header while holding shift or alt an alternative
data-sort-alt attribute will override data-sort.
`html`
Movie Name
Size
A
B
D
E
D
E
Using the data-sort-col attribute in thead > th, you can sort on a different column than the one that was clicked. For instance if you want to have colspans. Like so:
`html`
Category
Show
Overall
On Our Dates
First Sold Out
Comedy
Show 1
18/25
72%
3/4
75%
2022-07-30
...
Rowspans are not supported. Maybe I could do a half-assed implementation, but I don't think it would be worth it. You can read my justification in Issue 71
If you have a good idea, please let me know!
By adding asc to table, the default sorting direction will be ascending instead of descending
``html`
...
...
If you wish to sort by a different column when two values are equal, you can use the data-sort-tbr attribute, like so:
`html`
Year
Month
Day
2010
07
25
2010
11
12
2010
04
25
When clicking Year, if they are the same, we will sort on Month.
Adding class="n-last" to
| Text | Number |
|---|---|
| jkl | 0.4 |
| This will always be sorted after the others | |
| abc | 0 |
| def | 0.2 |
⚠️ _Note that a string of blank spaces is not considered null/empty.
will be sorted normally._Accessibility
Sortable is not very accessible in its raw form. It does not support screen readers, and it does not have any keyboard support. Including
sortable.a11y.min.js in your project will add some basic accessibility features.`html
...
`By including the file the global function
will automatically run through all existing .sortable tables, but you can also run it manually, like so:`js
enhanceSortableAccessibility([table1, table2,...etc.])
`The function adds an
to each th, as well as tabindex="0" to each th in the thead of each table, making it possible to tab through the headers. It updates the aria-label depending on the direction.If you want to import it instead:
`ts
import { enhanceSortableAccessibility } from 'sortable-tablesort/dist/esm/enhanceSortableAccessibility'
enhanceSortableAccessibility([table1, table2,...etc.])
`...or you can use the
flavour:`html
...
`Sort Events
The table element dispatches two custom events that bubble up the DOM tree:
-
: Fired when sorting begins
- sort-end: Fired when sorting is completeYou can listen for these events on any parent element, including the document itself:
`js
// Listen for events from any sortable table
document.addEventListener('sort-start', function (e) {
console.log('Sorting started on:', e.target) // logs the table element
})document.addEventListener('sort-end', function (e) {
console.log('Sorting complete on:', e.target) // logs the table element
})
// Or listen to a specific table
const table = document.querySelector('.sortable')
table.addEventListener('sort-start', () => console.log('Sorting started'))
table.addEventListener('sort-end', () => console.log('Sorting complete'))
`Sort on load
$3
If you wish to sort a table on load, I would recommend doing something like this:
html
Movie Name
Size
Release date
...
`Combine this with
| Movie Name | Size | Release date |
|---|
Thank you 🙏
- Nikita Dunajevs for the ascending sort idea!
- wodny for the alternative sorting idea!
- Nick Kocharhook for the colspan sorting idea!
- mxve for the nested elements inside
fix!- Christian Petersson and Abit Salihu for the sort on load example!
- GazHay for the idea to sort multiple
!- Gordan Ratkovic for the tiebreaker / secondary sort idea!
- chatcoda for the
/ sorting bug fix!- Christian Garbs for fixing the
dataset bug!- Witold Baryluk for pointing out some inefficiencies!
- Nick for raising a whole bunch of issues! 🤯️
- James Pudson for the empty last suggestion, AND for finding the "
data-sort ignored when empty" bug! 🥳️- Jojo-IO for the finding the "
parseFloat messes up time values" bug!- Steve Wirt for lifting the Accessibility issue! 🦾️
- GazHay for the sort events idea!
- deverac for the empty
tr` bug fix!- Richard Davies for nudging me into adding the "auto" version/flavour!
- fiskhandlarn for finding the whitespace bug!
- roxasthenobody98 for the time sorting suggestion!
- Troy Morehouse for finding the 'A11Y labels still appear on TH when class "no-sort" is set' bug!