Author: Christian Bach
Version: 2.7.12 (forked from version 2.0.5, changelog)
Licence:
Dual licensed under MIT
or GPL licenses.
Contents
- Introduction
- Demo
- Getting started
- Examples
- Configuration
- Widget Options (v2.1)
- Methods
- Events
- Download
- Compatibility
- Support
- 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:
- Multi-column sorting
- Multi-tbody sorting - see the options table below
- Parsers for sorting text, URIs, integers, currency, floats, IP addresses, dates (ISO, long and short formats), time. Add your own easily
- Support secondary "hidden" sorting (e.g., maintain alphabetical sort when sorting on other criteria)
- Extensibility via widget system
- Cross-browser: IE 6.0+, FF 2+, Safari 2.0+, Opera 9.0+
- Small code size
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
- Set an initial sorting order using options
- Sort table using a link outside the table
- Force a default sorting order
- Append a sort to the selected sorting order
- Child rows; how to add rows that sort with their parent row
- Child rows + filter widget; how they work together
- Direction of initial sort
- Disable sort
- Lock sort order
- Set initial sort order
- Using sortReset & sortRestart options
- Resetting the entire table sort (sortReset method) (v2.4.7)
- Using selectorSort option (v2.4)
- Sorting empty cells (v2.1.11)
- Change the default multi-sorting key
- Custom sort script (v2.2)
- Sorting Accented Characters (v2.24; languages)
- Sorting with Multiple Tbodies (v2.2)
- Sorting Across Multiple Columns (v2.3)
- Show a processing icon during sorting/filtering (v2.4)
Parsers / Extracting Content
- Dealing with digits!
- Dealing with text strings in numerical sorts (v2.0.10)
- Disable or set the column parser using class names (v2.0.11)
- Disable or set the column parser using jQuery Data (v2.3)
- Changing the date format (v2.0.23)
- Parser, writing your own
- Parser, writing your own, advanced use (v2.1)
- Dealing with markup inside cells (textExtraction function)
Widgets / Plugins
- Applying widgets
- Columns widget (v2.0.17)
- Filter widget (v2.0.18)
- Filter widget, custom (v2.3.6)
- Filter widget, formatter (part 1 and part 2) New v2.7.7.
- UITheme widget - jQuery UI theme (v2.0.9; Modified v2.4)
- UITheme widget - Bootstrap (v2.4)
- Resizable Columns widget (v2.0.23.1; Modified v2.7.4)
- Save sort widget (v2.0.27)
- Sticky header widget (v2.0.21.1)
- Zebra stripe widget
- Widgets, writing your own
- Pager plugin
- Pager plugin - ajax (v2.1)
- Pager plugin + filter widget (v2.4)
Advanced
Adding / Removing Content
- Initializing tablesorter on a empty table
- Appending table data with ajax
- Adding a table row (v2.0.16)
- Update the table after cell content has changed
- Pager plugin - examples of how to add and remove rows
Change Header Style
- UITheme widget (v2.0.9)
- Modifying the Header during rendering.
- Modifying the Header using a template. New! v2.7
Other
Options & Events
- Triggers sortEnd and sortStart (Displaying sorting progress)
- Extending default options
- Enabling debug mode
Playgrounds & Other demos
- tablesorter basic demo (includes widgets)
- tablesorter basic demo using jQuery UI theme
- tablesorter basic demo with pager plugin
- tableSorter LESS theme; modify the colors dynamically in this LESS theme demo!
- Check out the home wiki page more demos!
Metadata - setting inline options
- *Note* you can use class names (version 2.0.11+, demo), or jQuery data (version 2.3+, demo) instead of meta data
- Set a initial sorting order using metadata.
- Disable header using metadata
- Setting column parser using metadata
Configuration
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.
|
Property |
Type |
Default |
Description |
Link |
---|
Widget Options
Applied Order | Name | Requires jQuery | Limiting function |
---|---|---|---|
1 | uitheme | v1.2.6 | |
2 | stickyHeaders | v1.2.6 | |
3 | saveSort | v1.4.1 | 1.4.1 (parseJSON)* |
4 | resizable | v1.4.1* | 1.4 (isEmptyObject); 1.4.1 (parseJSON)* |
5 | filter | v1.4.3 | 1.4.3 (nextUntil) |
6 | columns | v1.2.6 | |
7 | zebra | v1.2.6 | |
8 | pager | v1.2.6 |
widgetOptions
. Thanks to thezoggy for putting together this jQuery-widget compatibility table, but please note:
- The applied order will not change depending on the widgets applied, but the numbers will change.
- The widgets are actually applied in reverse alphabetical order. This includes any custom widget names, so a custom widget named "zoom" will be the first applied widget. The only exception is the zebra widget which will always be the last widget applied.
- The pager, being a plugin, is actually initialized after tablesorter has initialized and all selected widgets applied.
- * The
saveSort
andresizable
widgets use the$.tablesorter.storage
function by default and thus need theparseJSON
function which is available in jQuery 1.4.1+.
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 |
Property |
Type |
Default |
Description |
Link |
---|
Methods
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. | |||
search | Trigger the filter widget to update the search from current inputs and/or selections. Updated! v2.4. | Ex: 1 2 3 | ||
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. |
Method |
Description |
Link |
---|
Events
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 |
Event |
Description |
Link |
---|
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:- jQuery (1.2.6 or higher; some demos & HTML5 data-attributes need jQuery 1.4.3+)
- jquery.tablesorter.min.js (19kb, minified for production - please put the file on your server)
- jQuery Metadata 2.1 (4kb, required for setting inline options)
- jquery.tablesorter.js (47kb/23kb min)
- jquery.tablesorter.pager.js (16kb/8kb min, demo)
- jquery.tablesorter.widgets.js (36kb/17kb min, includes the jQuery UI theme, columns styling, resizable columns, filter, sticky header and save sort widgets.
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:
- Firefox 2+
- Internet Explorer 6+
- Safari 2+
- Opera 9+
- Konqueror
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