tablesort

In tables with complex header structures (like colspan), you can explicitly link a header to specific data cells using the data-sort-column-key attribute. Apply this attribute to both the <th> and the corresponding <td> elements to ensure the correct data is used for sorting.

<table class='sort'>
<thead>
  <tr>
    <th>Product</th>
    <th colspan="2" data-sort-column-key="price">Price</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>Apples</td>
    <td data-sort-column-key="price">20</td>
  </tr>
</tbody>
</table>

If cell text is not normalized, you can provide a hidden value for sorting using the data-sort attribute on a <td>.

Alternatively, you can specify a custom attribute name to use for sorting by passing the sortAttribute option to the Tablesort constructor.

<!-- Use data-sort for custom values -->
<td data-sort='1357656438'>01/08/13 @ 8:47:18am EST</td>

// Use a custom attribute instead of data-sort
var table = document.getElementById('table-id');
var sort = new Tablesort(table, { sortAttribute: 'data-custom-sort-val'});

To have a table automatically sorted by a specific column when the page loads, add the data-sort-default attribute to the desired <th> element.

<th data-sort-default>Born</th>

To use Tablesort in a standard HTML environment, include the core tablesort.min.js script, followed by any specific sort type scripts you require (such as tablesort.number.js or tablesort.date.js). Initialize the sorting functionality by creating a new Tablesort instance and passing the target table element.

<script src='tablesort.min.js'></script>

<!-- Include sort types you need -->
<script src='tablesort.number.js'></script>
<script src='tablesort.date.js'></script>

<script>
  new Tablesort(document.getElementById('table-id'));
</script>

You can force a specific sorting method for a column by adding data-sort-method='[methodName]' to the <th> element. The value must correspond to the name of a registered sort function (e.g., dotsep).

<th data-sort-method='dotsep'>Version</th>

If a table has multiple heading rows, you can designate which <tr> enables sorting by adding data-sort-method='thead' to that row.

<thead>
  <tr data-sort-method='thead'>
    <th>Sort Row</th>
  </tr>
  <tr>
    <th>Not Sort Row</th>
  </tr>
</thead>

For module-based environments, import tablesort from the package. You can then invoke it by passing the target element and an optional options object.

import tablesort from 'tablesort';

tablesort(el, options);

Tablesort defaults to ascending order. You can change the global sort order for a table by passing an options object with descending: true to the constructor.

To change the sort order for a specific column only, add the data-sort-reverse attribute to the <th> element.

Note: If using the default CSS, you will need to reverse the class names that style the arrows when using descending order.

// Set global descending order
new Tablesort(document.getElementById('table-id'), {
  descending: true
});

<!-- Set descending order for a single column -->
<th data-sort-reverse>A table header</th>

To prevent specific columns or rows from being sorted, add the attribute data-sort-method='none' to the corresponding <th> (for columns) or <tr> (for rows) element.

<th data-sort-method='none'>Name</th>

<tr data-sort-method='none'>
  <td>1</td>
  <td>Gonzo the Great</td>
</tr>

You can add custom sorting logic using Tablesort.extend(name, test, compare).

• name: The identifier for your new sort type.
• test: A function that takes an item (the table cell value) and returns a boolean (e.g., via a Regular Expression) to determine if the item matches the sort criteria.
• compare: A function that defines the custom comparison logic between two values a and b. It should return a number (e.g., -1, 1, or 0).

Tablesort.extend('name', item => {

  // Regular expression to test against.
  // `item` is a table value to evaluate.
  return /foo/.test(item);
}, (a, b) => {

  // Custom sort functionality goes here.
  // e.g var n = (a > b) ? -1 : 1;
  return n;
});

If you dynamically add new rows to a table (e.g., via Ajax), you must call the .refresh() method on your Tablesort instance to re-apply sorting to the updated content.

var table = document.getElementById('table-id');
var sort = new Tablesort(table);

// After adding new rows:
sort.refresh();