Author: Christian Bach
Version: 2.7.12 (forked from version 2.0.5, changelog)
Licence: Dual licensed under MIT or GPL licenses.

Contents

  1. Introduction
  2. Demo
  3. Getting started
  4. Examples
  5. Configuration
  6. Widget Options (v2.1)
  7. Methods
  8. Events
  9. Download
  10. Compatibility
  11. Support
  12. Credits

Introduction

tablesorter is a jQuery plugin for turning a standard HTML table with THEAD and TBODY tags into a sortable table without page refreshes. tablesorter can successfully parse and sort many types of data including linked data in a cell. It has many useful features including:

Demo

Account #
First Name
Last Name
Age
Total
Discount
Difference
Date
A1 Bruce Almighty 45 $153.19 44.7% +77 Jan 18, 2001 9:12 AM
A33 Clark Kent 18 $15.89 44% -26 Jan 12, 2003 11:14 AM
A42a Bruce Evans 22 $13.19 11% 0 Jan 18, 2007 9:12 AM
A42b Peter Parker 28 $9.99 20.9% +12.1 Jul 6, 2006 8:14 AM
A102 Bruce Evans 22 $13.19 11% -100.9 Jan 18, 2007 9:12 AM
A255 John Hood 33 $19.99 25% +12 Dec 10, 2002 5:14 AM

TIP! Sort multiple columns simultaneously by holding down the shift key and clicking a second, third or even fourth column header!

Getting started

To use the tablesorter plugin, include the jQuery library and the tablesorter plugin inside the <head> tag of your HTML document:

<!-- choose a theme file -->
<link rel="stylesheet" href="/path/to/theme.default.css">
<!-- load jQuery and tablesorter scripts -->
<script type="text/javascript" src="/path/to/jquery-latest.js"></script>
<script type="text/javascript" src="/path/to/jquery.tablesorter.js"></script>

<!-- tablesorter widgets (optional) -->
<script type="text/javascript" src="/path/to/jquery.tablesorter.widgets.js"></script>

tablesorter works on standard HTML tables. You must include THEAD and TBODY tags:

<table id="myTable" class="tablesorter">
  <thead>
    <tr>
      <th>Last Name</th>
      <th>First Name</th>
      <th>Email</th>
      <th>Due</th>
      <th>Web Site</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Smith</td>
      <td>John</td>
      <td>jsmith@gmail.com</td>
      <td>$50.00</td>
      <td>http://www.jsmith.com</td>
    </tr>
    <tr>
      <td>Bach</td>
      <td>Frank</td>
      <td>fbach@yahoo.com</td>
      <td>$50.00</td>
      <td>http://www.frank.com</td>
    </tr>
    <tr>
      <td>Doe</td>
      <td>Jason</td>
      <td>jdoe@hotmail.com</td>
      <td>$100.00</td>
      <td>http://www.jdoe.com</td>
    </tr>
    <tr>
      <td>Conway</td>
      <td>Tim</td>
      <td>tconway@earthlink.net</td>
      <td>$50.00</td>
      <td>http://www.timconway.com</td>
    </tr>
  </tbody>
</table>

Start by telling tablesorter to sort your table when the document is loaded:

$(function(){
  $("#myTable").tablesorter();
});

Click on the headers and you'll see that your table is now sortable! You can also pass in configuration options when you initialize the table. This tells tablesorter to sort on the first and second column in ascending order.

$(function(){
  $("#myTable").tablesorter({ sortList: [[0,0], [1,0]] });
});

NOTE! tablesorter will auto-detect most data types including numbers, dates, ip-adresses for more information see Examples

Examples

These examples will show what's possible with tablesorter. You need Javascript enabled to run these samples, just like you and your users will need Javascript enabled to use tablesorter.

Basic

Sorting

Parsers / Extracting Content

Widgets / Plugins

Advanced

Adding / Removing Content

Change Header Style


Other

Options & Events

Playgrounds & Other demos

Metadata - setting inline options


Configuration

tablesorter has many options you can pass in at initialization to achieve different effects
TIP! Click on the link in the property column to reveal full details (or toggle|show|hide all) or double click to update the browser location.
Property
Type
Default
Description
Link
Property Type Default Description Link
cancelSelection Boolean true Indicates if tablesorter should disable selection of text in the table header (TH). Makes header behave more like a button.
cssAsc String "tablesorter-headerAsc" The CSS style used to style the header when sorting ascending. Default value Changed! v2.5.
cssChildRow String "tablesorter-childRow" Add this css class to a child row that should always be attached to its parent. Click on the "cssChildRow" link to toggle the view on the attached child row. Previous default was "expand-child" (Changed in v2.4). Ex:1 2
cssDesc String "tablesorter-headerDesc" The CSS style used to style the header when sorting descending. Default value Changed! v2.5.
cssHeader String "tablesorter-header" The CSS style used to style the header in its unsorted state.
cssHeaderRow String "tablesorter-headerRow" The CSS style used to style the header row (v2.4).
cssIcon String "tablesorter-icon" The CSS style used to style the header cell icon. Modified! v2.7.
cssInfoBlock String "tablesorter-infoOnly" All tbodies with this class name will not have its contents sorted. (v2.2).
cssProcessing String "tablesorter-processing" This class name is added to the header cell that is currently being sorted or filted. To prevent this class name from being added, set the showProcessing option to false (v2.4).
dateFormat String "mmddyyyy" Set the date format. Here are the available options. (Modified v2.0.23). Example
debug Boolean false Boolean flag indicating if tablesorter should display debuging information useful for development. Example
delayInit Boolean false Setting this option to true will delay parsing of all table cell data until the user initializes a sort. This speeds up the initialization process of very large tables, but the data still needs to be parsed, so the delay is still present upon initial sort. Example
emptyTo String "bottom" Boolean flag indicating how tablesorter should deal with empty table cells. (Modified v2.1.16). Example
headerList Array [ ] (empty array) Internal list of each header element as selected using jQuery selectors in the selectorHeaders option. Not really useful for normal usage.
headers Object null An object of instructions for per-column controls in the format: headers: { 0: { option: setting }, ... } Ex:1 2 3 4
headerTemplate String '{content} {icon}' This is a template string which allows adding additional content to the header while it is being built. New! v2.7. Example
ignoreCase Boolean true When true, text sorting will ignore the character case. If false, upper case characters will sort before lower case. (v2.2).
initWidgets Boolean true Apply widgets after table initializes (v2.3.5).
onRenderHeader Function null This function is called after content is to the TH tags (after the template is procressed and added). You can use this to modify the HTML in each header tag for additional styling. Example
onRenderTemplate Function null This function is called after the template string has been built, but before the template string is applied to the header and before the onRenderHeader function is called. New! v2.7. Example
parsers Object { } Internal list of all of the parsers. Here is a complete list of default parsers: Ex:1 2 3
selectorHeaders String "> thead th, > thead td" jQuery selectors used to find cells in the header.
selectorRemove String "tr.remove-me" This CSS class name can be applied to all rows that are to be removed prior to triggering a table update. (v2.1).
selectorSort String "th, td" jQuery selector of content within selectorHeaders that is clickable to trigger a sort (v2.4). Example
serverSideSorting Boolean false Set to true if the server is performing the sorting. The ui and events will still be used (v2.5.3).
showProcessing Boolean false Show an indeterminate timer icon in the header when the table is sorted or filtered. Please note that due to javascript processing, the icon may not show as being animated. I'm looking into this further and would appreciate any feedback or suggestions with the coding (v2.4). Example
sortAppend Array null Use to add an additional forced sort that will be appended to the dynamic selections by the user. Example
sortForce Array null Use to add an additional forced sort that is prepended to sortList. Example
sortInitialOrder String "asc" The direction a column sorts when clicking the header for the first time. Valid arguments are "asc" for Ascending or "desc" for Descending.
Ex:1 2
sortList Array null Use to add an initial sort to the table. Example
sortLocaleCompare Boolean false Boolean flag indicating if certain accented characters within the table will be replaced with their equivalent characters. (Modified v2.2). Example
sortMultiSortKey String "shiftKey" The key used to select more than one column for multi-column sorting. Defaults to the shift key. The other options are "ctrlKey" or "altKey". Reference: https://developer.mozilla.org/en/DOM/MouseEvent Example
sortReset Boolean false Setting this option to true will allow you to click on the table header a third time to reset the sort direction. (v2.0.27). Example
sortResetKey String "ctrlKey" The key used to reset sorting on the entire table. Defaults to the control key. The other options are "shiftKey" or "altKey". Reference: https://developer.mozilla.org/en/DOM/MouseEvent
sortRestart Boolean false Setting this option to true will start the sort with the sortInitialOrder when clicking on a previously unsorted column. (v2.0.31). Example
stringTo String "max" Boolean flag indicating how tablesorter should deal with text inside of numerically sorted columns. (v2.1.16). Example
tableClass String "tablesorter" This class was required in the default markup in version 2.0.5. But in version 2.0.6, it was added as an option.
textExtraction String Or Function "simple" Defines which method is used to extract data from a table cell for sorting. The built-in option is "simple" which is the equivalent of doing this inside of the textExtraction function: $(node).text();. Example
textSorter Function null Replace the default sorting algorithm with a custom one using this option. Example
theme String "default" This option will add a theme css class name to the table "tablesorter-{theme}" for styling (v2.4). Example
usNumberFormat Boolean true Indicates how tablesorter should deal with a numerical format: (v2.1.3). Example
widgetOptions Object { } In version 2.1, all widget options have been moved into this option. This is a move to store all widget specific options in one place so as not to polute the main table options. All current widgets have been modified to use this new option. (v2.1). Example
widgets Array [ ] (empty array) Initialize widgets using this option ( e.g. widgets : ['zebra'], or custom widgets widgets: ['zebra', 'myCustomWidget'];, see this demo on how to write your own custom widget ). Example
widthFixed Boolean false Indicates if tablesorter should apply fixed percentage-based widths to the table columns (modified v2.4). Example
Deprecated Options
widgetColumns Object with Array { css:[ "primary", "secondary", "tertiary" ] } This option is being deprecated! It has been replaced by widgetOptions.columns; but is still available for backwards compatibility.
widgetUitheme Object with Array { css: [ "ui-icon-arrowthick-2-n-s", "ui-icon-arrowthick-1-s", "ui-icon-arrowthick-1-n" ] } This option is being deprecated! It has been replaced by widgetOptions.uitheme; but is still available for backwards compatibility.
widgetZebra Object with Array { css: [ "even", "odd" ] } This option is being deprecated! It has been replaced by widgetOptions.zebra; but is still available for backwards compatibility.

Widget Options

Applied Order
Name
Requires jQuery
Limiting function
1uithemev1.2.6
2stickyHeadersv1.2.6
3saveSortv1.4.11.4.1 (parseJSON)*
4resizablev1.4.1*1.4 (isEmptyObject); 1.4.1 (parseJSON)*
5filterv1.4.31.4.3 (nextUntil)
6columnsv1.2.6
7zebrav1.2.6
8pagerv1.2.6

tablesorter widgets have many options, and to better organize them, they now are grouped together inside of the widgetOptions. Thanks to thezoggy for putting together this jQuery-widget compatibility table, but please note:
TIP! Click on the link in the property column to reveal full details (or toggle|show|hide all) or double click to update the browser location.
Property
Type
Default
Description
Link
Property Type Default Description Link
columns Array [ "primary", "secondary", "tertiary" ] Columns widget: When the column styling widget is initialized, it automatically applied the default class names of "primary" for the primary sort, "secondary" for the next sort, "tertiary" for the next sort, and so on (add more as needed)... (Modified v2.1). Example
columns_tfoot Array true Columns widget: If true, the class names from the columns option will also be added to the table tfoot (v2.4). Example
columns_thead Array true Columns widget: If true, the class names from the columns option will also be added to the table thead (v2.4). Example
filter_childRows Boolean false Filter widget: If there are child rows in the table (rows with class name from "cssChildRow" option) and this option is true and a match is found anywhere in the child row, then it will make that row visible. (Modified v2.1).
filter_columnFilters Boolean true Filter widget: If true, a filter will be added to the top of each table column (v2.4).
filter_cssFilter String 'tablesorter-filter' Filter widget: This is the class name applied to each input within the filter row. If you change it from the default class name of "tablesorter-filter" make sure you also update the css! (v2.1). Example
filter_formatter Object null Filter widget: This option allows you to add custom controls within the filter widget row. New! v2.7.7
Ex: 1 2
filter_functions Object null Filter widget: Customize the filter widget by adding a select dropdown with content, custom options or custom filter functions (v2.3.6). Example
filter_hideFilters Boolean false Filter widget: Set this option to true to hide the filter row initially. The rows is revealed by hovering over the filter row or giving any filter input/select focus (v2.4). Example
filter_ignoreCase Boolean true Filter widget: Set this option to false to make the column content search case-insensitive, so typing in "a" will not find "Albert". (v2.3.4) Example
filter_reset String null Filter widget: jQuery selector string of an element used to reset the filters (v2.4). Example
filter_searchDelay Numeric 300 Filter widget: Set this option to the number of milliseconds to delay the search. (v2.3.4).
filter_serversideFiltering Boolean false Filter widget: Set this option to true if filtering is performed on the server-side (v2.5.3).
filter_startsWith Boolean false Filter widget: Set this option to true to use the filter to find text from the start of the column, so typing in "a" will find "albert" but not "frank", both have a's. (v2.1). Example
filter_useParsedData Boolean false Filter widget: If true, ALL filter searches will only use parsed data (v2.4).
resizable Boolean true Resizable widget: If this option is set to false, resized column widths will not be saved. Previous saved values will be restored on page reload (v2.4). Example
saveSort Boolean true saveSort widget: If this option is set to false, new sorts will not be saved. Any previous saved sort will be restored on page reload (v2.4). Example
stickyHeaders String "tablesorter-stickyHeader" Sticky Headers widget: This is the class name applied to the sticky header row (tr). If you change it from the default class name of "tablesorter-stickyHeader" make sure you also update the css! (v2.1). Example
uitheme String "jui" Instead of the array of icon class names, this option now contains the name of the theme. Currently jQuery UI ("jui") and Bootstrap ("bootstrap") themes are supported. To modify the class names used, extend from the theme (updated v2.4) Example
zebra Array [ "even", "odd" ] zebra widget: When the zebra striping widget is initialized, it automatically applied the default class names of "even" and "odd". (Modified v2.1). Example

Methods

tablesorter has some methods available to allow updating, resorting or applying widgets to a table after it has been initialized.
TIP! Click on the link in the method column to reveal full details (or toggle|show|hide all) or double click to update the browser location.
Method
Description
Link
addRows Use this method to add table rows. (v2.0.16). Example
appendCache Update a table that has had its data dynamically changed; used in conjunction with "update".
applyWidgetId Apply the selected widget to the table, but the widget will not continue to be applied after each sort. See the example, it's easier than describing it. Example
applyWidgets Apply the set widgets to the table. This method can be used after a table has been initialized, but it won't work unless you update the configuration settings. See the example, it's easier than describing it. Example
destroy Use this method to remove tablesorter from the table.
refreshWidgets Refresh the currently applied widgets. Depending on the options, it will completely remove all widgets, then re-initialize the current widgets or just remove all non-current widgets. New v2.4. Example
sorton Use this method to sort an initialized table in the desired order. Example
sortReset Use this method to reset the table to it's initial unsorted state. New v2.4.7. Example
update Update the stored tablesorter data and the table. Example
updateCell Update a table cell in the tablesorter data. Example
Widget Methods
filterReset Trigger the filter widget to reset the search criteria. New! v2.7.7. Example
saveSortReset Trigger the saveSort widget to clear any saved sorts for that specific table. New! v2.7.11.
Pager Methods
pageSet Trigger the pager to change the current page. New! v2.7.7.
pageSize Trigger the pager to change the page size. New! v2.7.4.

Events

tablesorter has some methods available to allow updating, resorting or applying widgets to a table after it has been initialized.
TIP! Click on the link in the event column to reveal full details (or toggle|show|hide all) or double click to update the browser location.
Event
Description
Link
initialized This event fires when tablesorter has completed initialization. (v2.2).
sortBegin This event fires immediately before tablesorter begins resorting the table.
sortEnd This event fires when tablesorter has completed resorting the table. Example
sortStart This event fires immediately after the tablesorter header has been clicked, initializing a resort. Example
updateComplete This event fires after tablesorter has completed updating. (v.2.3.9)
Pager Events
pageMoved This event fires when the pager plugin begins to change to the selected page. New v2.4.4. Example
pagerBeforeInitialized This event fires after all pager controls have been bound and set up but before the pager formats the table or loads any ajax data. New v2.4.4.
pagerChange This event fires when the pager plugin begins to render the table on the currently selected page. (v2.0.7). Example
pagerComplete This event fires when the pager plugin has completed its render of the table on the currently selected page. (v2.0.7). Example
pagerInitialized This event fires when the pager plugin has completed initialization. New v2.4.4. Example
Widget Events
filterEnd Event triggered when the filter widget has finished processing the search. New v2.4. Example
filterInit Event triggered when the filter widget has finished initializing. New v2.4. Example
filterStart Event triggered when the filter widget has started processing the search. New v2.4. Example

Download

Full release - Plugin, Documentation, Add-ons, Themes. Download: zip or tar.gz

Pick n choose - Place at least the required files in a directory on your webserver that is accessible to a web browser. Record this location.

Required: Optional / Add-Ons: Themes:

Theme zip files have been removed. There are now numerous themes available which can be seen here

Browser Compatibility

tablesorter has been tested successfully in the following browsers with Javascript enabled:

jQuery Browser Compatibility

Support

If you are having a problem with the plugin or you want to submit a feature request, please submit an issue.

If you would like to contribute, fork a copy on github.

Some basic unit testing has been added. If you would like to add more or report a problem, please use the appropriate link above. New! v2.6.

Support is also available from stackoverflow.

For questions about jQuery, try irc, stackoverflow, or the jQuery forums.

Credits

Written by Christian Bach.

Documentation written by Brian Ghidinelli, based on Mike Alsup's great documention.
Additional & Missing documentation, alphanumeric sort, numerous widgets, unit testing and other changes added by Mottie.

John Resig for the fantastic jQuery