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.
Documentation
- See the full documentation.
- All of the original document pages have been included.
- Information from my blog post on undocumented options and lots of new demos have also been included.
- Change log moved from included text file into the wiki documentation.
Demos
- Basic alpha-numeric sort Demo.
- Links to demo pages can be found within the main documentation.
- More demos & playgrounds - updated in the wiki pages.
Features
- Multi-column alphanumeric sorting.
- Multi-tbody sorting - see the options table on the main document page.
- Parsers for sorting text, alphanumeric text, URIs, integers, currency, floats, IP addresses, dates (ISO, long and short formats) & time. Add your own easily.
- Support for ROWSPAN and COLSPAN on TH elements.
- 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.
- Works with jQuery 1.2.6+ (jQuery 1.4.1+ needed with some widgets).
Licensing
- Copyright (c) 2007 Christian Bach.
- Original examples and docs at: http://tablesorter.com.
- Dual licensed under the MIT and GPL licenses.
Change Log
View the complete listing here.
Version 2.5 (11/22/2012)
- Improved multi-column sorting
- Huge thanks to Nick Craver for making multicolumn sorting no longer uses an
eval()during the sort! - This change improves performance of the sort across all browsers.
- It also allows use of numerous minifier scripts.
- See pull request #177 for more details.
- Huge thanks to Nick Craver for making multicolumn sorting no longer uses an
- Fixed using
addRowson an empty table, issue #179. - Fixed inconsistencies in the usage of sort up (ascending) and sort down (descending) in the javascript and css.
- Updated the
cssAscdefault value totablesorter-headerAsc. - Updated the
cssDescdefault value totablesorter-headerDesc. - All css themes now include these new class names. References to older class names were not removed, but they will be removed in version 3.
- Renamed image files and switched data URIs to match these changes.
- This fixes issue #173. Thanks bitti!
- Updated the
- Updated all theme css files to use image data URIs instead of the images.
- The images are all still contained in the
css/imagesdirectory. - References to the image files have been commented out instead of removed.
- The images are all still contained in the
Version 2.4.8 (11/15/2012)
- Fixed a few issues:
- The pager plugin will no longer cause a javascript error when initialized on a table that doesn't have tablesorter applied.
- The sticky header widget will now add the cloned table with the sticky header AFTER the table, in case the table has an ID applied.
- See issue #175 for more details.
Version 2.4.7 (11/14/2012)
- Added
sortResetmethod. - Added a live LESS theme demo at codepen.io.
- Fixed QtWebkit browsers (includes Safari & Arora) error when running jQuery v1.8+:
- The problem was with a selector which worked without any problems until jQuery v1.8+.
- Fixes issue #132 & #174.
- Fixed sticky header issues
- Sticky header bug when the sticky header contained a
sticky-falserow - see issue #172. - Javascript error fixed in IE8 - see issue #.
- Sticky header breaking when first rows hidden - see issue #168.
- Sticky header bug when the sticky header contained a
Version 2.4.6 (10/25/2012)
- Filter widget select dropdowns will now trim extra spaces before adding them as an option. Fixes issue #161.
- Fixed pager addon page size selector. There is an order of priority:
- If an option has
selected="selected"as an attribute, it will override the pagersizeoption. - Pager
sizeoption is no longer ignored even if no option in the page size select is selected. - Fixes an problem brought up in issue #122.
- If an option has
- The pager plugin will now update when an
updateCompleteorfilterEndevent is triggered on the table.- Added to make the pager plugin work with this quicksearch plugin.
- To make them work together, filtered rows need to get a class name of
filteredbefore triggering the updateComplete event. - See issue #160 for more details.
Version 2.4.5 (10/17/2012)
- The filter widget no longer builds the filter row when all columns have
filter-falseset. Fixes issue #156. - Pager plugin updates:
- Added an optional ajax url parameter to include the current sort per column
- Add the
{sortList:col}parameter, wherecolis the actual parameter added to the URL. - So this parameter
{sortList:sort}with a sortList value of[[2,0],[3,0]]becomes&sort[2]=0&sort[3]=0in the URL. - Thanks to trevorbernard for the enhancement request from issue #155.
- Add the
- Fixed an issue with the
cssPageSizeandcssGotonot becoming disabled when multiple elements exist. Fixes issue #157.
- Added an optional ajax url parameter to include the current sort per column
Version 2.4.4 (10/15/2012)
- Updated pager plugin:
- Added
pagerInitializedevent which is triggered after the pager has completed initialization. - Added
pageMovedevent which may fire before thepagerCompleteevent when ajax processing is involved, or after thepagerCompleteon normal use. See issue #153.
- Added
Version 2.4.3 (10/13/2012)
- Fixed an error with the filter widget using parsed data. Fixes issue #149.
Version 2.4.2 (10/13/2012)
- Updated the Bootstrap theme:
- Bootstrap demo version updated to v2.1.1.
- Darkened header gradient - see issue #142.
- Made some other tweaks to clean up the theme - bold header text, select box sizes (pager), etc.
- Updated LESS theme to include filter widget styling, column widget footer styling and themes.
- Updated
updateCellmethod to not use jQuery'sclosest()function which is not supported by jQuery v1.2.6. - Changed tablesorter
selectorRemoveoption default to".remove-me"(see the pager plugin ajax change below). - Fixed sticky headers not scrolling horizontally. Fixes issue #.
- Fixed pager plugin Ajax:
- Ajax loaded tables will no longer hide pages other than the first. Fixes issue #151.
- Ajax header data now properly replaces the header text.
- The error message row is now added with the class name from the
selectorRemoveoption.
Version 2.4.1 (9/29/2012)
- Fixed uitheme widget:
- A second div is now wrapped around the table cell contents.
- This allows using relative & absolute positioning on the content as Firefox does not support this directly on table cells.
- Fixed support for jQuery v1.2.6
- Core modified to not use
closest()function. - Resizable widget modified to not use
closest()&isEmptyObjectfunctions.
- Core modified to not use
Version 2.4 (9/27/2012)
-
Core changes:
-
Table bodies are now detached before processing the contents. There is a noticable speed increase when sorting large tables, especially in IE. Fix for issue #72 and possibly issue #75.
-
Changed
cssChildRowoption default fromexpand-childtotablesorter-childRowto make it more clear. -
Changed
selectorHeadersoption default from'> thead th'to'> thead th, > thead td'to include non-header cells. -
Fixed
sortAppendbeing applied multiple times when sorting multiple columns. Fix for issue #115. -
Fixed
updateCellmethod to correctly target the table cell from the cache. -
Fixed something, somewhere to fix issue #128 LOL... darn you IE!
-
Updated the
widthFixedoption to set the column widths as a percentage instead of pixels to better resize the table dynamically. -
Updated the script so that data-column attributes are no longer removed from disabled columns. This fixes an issue where
filter-falsedoesn't apply to disabled columns. -
Updated the
widgetsoption so that the order of widgets no longer matters. The array now is sorted in reverse alphabetical order, but the zebra widget is always applied last. See the table here. -
Updated the
$.tablesorter.isDigit()function to ensure that no errors pop up when giving it an element of type number. Fix for issue #121. -
Updated the natural sort function to better sort numbers with leading zeros. See this issue for more details.
-
Updated the code to always check that the
sortListoption contains numeric values. See issue #127. -
Updated the date parser to not be so rigid. See issue #125.
-
Updated several internal functions to keep tablesorter compatible with jQuery 1.2.6. Fixs issue #124.
-
Tablesorter can no longer be initialized multiple times on the same table, unless the destroy method is called.
-
Bound events now have
unbindexecuted beforebindto fix an issue with Microsoft ajax.net. See issue #119. -
Added
cssHeaderRowoption- This option contains the class name added to the header row.
- Previously it got the same class name as
cssHeader. - Default value is
"tablesorter-headerRow".
-
Added
cssIconoption:- This option contains the class name added to the
<i>element that is now automatically added to every header cell. - To prevent the plugin from adding an
<i>element to the headers, set this option to an empty string. - Default value is
"tablesorter-icon".
- This option contains the class name added to the
-
Added
themeoption & new themes!- Default theme is now
default. - Note that ALL of the documentation demos now need the theme option set to
"blue"to apply the blue theme. - Thanks to thezoggy, numerous themes have been added including default, ice, black-ice, dark & dropbox.
- Updated hovered row styling to include child rows in some themes (blue, green and less themes).
- See the column widget update for details on styling of the thead and tfoot cells as well.
- Removed the blue and green zipped theme files.
- Default theme is now
-
Added
selectorSortoption:- This option allows you to set which element within the table header triggers the sort.
- Previously the entire header cell would trigger a sort so any extra elements within the cell would not be clickable.
- See issue #137.
-
Added
cssProcessingoption:- When true, an indeterminate progress icon is added to the header while tablesorter is sorting or filtering columns.
- It is disabled by default, but can be enabled by setting the
showProcessingoption totrue. - The icon can also be shown using the API:
$.tablesorter.isProcessing(table, toggle, $ths);- The
tableparameter is the table to target. -
toggleis a boolean which whentruewill add thecssProcessingoption class name to the header. - The last parameter
$thsis optional. When set it will target specific header cells. If undefined, only the sorted headers will be targetted.
- The
- Note that for small tables, this processing icon may quickly flash and may be distracting. In larger tables, it will be more visible, but may not animate. I believe this is because of all the javascript processing going on (single threaded) prevents the animation from occurring - I'll try to find a better solution.
-
-
Parsers:
- All parsers now have publically available methods.
- Access the parsers using
$.tablesorter.parsers. - Get the desired parser code using
parser = $.tablesorter.getParserById("parser_name").
-
Widgets:
- All widgets now have publically available methods:
- Access the widgets using
$.tablesorter.widgets. - Get the desired widget code using
$.tablesorter.getWidgetById("widget_name"). - Apply all selected widgets from the
widgetsoption directly using$.tablesroter.applyWidget(table, initialize);, whereinitializeis a boolean indicating to run the widget'sinitfunction versus theformatfunction. This is the same as triggering applyWidgets on the table. - All widgets now have a
removefunction which when called will remove the widget from the table, see the writing custom widgets demo page for an example. - Updated the
destroymethod to call all widget's remove function, if it exists. - Added a method to refresh widgets:
- Trigger this method using
$('table').trigger('refreshWidgets', [doAll, dontapply]);, or call it directly using$.tablesorter.refreshWidgets(table, doAll, dontapply) - If
doAllistrueit removes all widgets from the table. Iffalseonly non-current widgets (from thewidgetsoption) are removed. - When done removing widgets, the widget re-initializes the currently selected widgets, unless the
dontapplyparameter istrueleaving the table widget-less. - Note that if the
widgetsoption has any named widgets, they will be re-applied to the table when it gets resorted. So if you want to completely remove all widgets from the table, also clear out the widgets option$('table')[0].config.widgets = []; - Enhancement request from issue #112.
- Trigger this method using
- Added a jQuery compatibility table to the WidgetOptions section to show the limitations of each widget. See issue #124.
-
Columns widget updates:
- The column class names from the
widgetOptions.columnsoption can now be applied to the header row (including the sticky header) and footer row. - Added a new option named
columns_theadwhich istrueby default. Set it tofalseto not add the columns class name to the header. - Added a new option named
columns_tfootwhich istrueby default. Set it tofalseto not add the columns class name to the footer. - In addition to the column class name, the tfoot also gets the class name for an ascending or desending sort obtained from the
cssAscandcssDescoption. - Added a remove function method.
- The column class names from the
-
Filter widget changes:
-
Added the ability to enter operators into the filter. Added
< <= >= > ! =.- To find values greater than 10, enter
>10. - To find letters less than M, enter
<m, but to find letters greater than M, enter>=n, because>mwill includemabecausema > m. - To find people that aren't George, enter
!Georgeor to only look for males, enter!female. This doesn't work in the quick search filter because - Exact matches can be done using quotes, as before, or by using an equal sign
=, e.g. find the exact number 10 by using10=. -
Note #1 In currency, percent or other numerical columns with numbers, the operators will ignore these extra symbols when parsing the value. So to find values greater than 10%, ignore the percent sign and use
> 10. -
Note #2 when using any of the above operators, the child row content is ignored even if
filter_childRowsis set totrue.
- To find values greater than 10, enter
-
Added
filter_columnFiltersoption which whentruewill add a filter to each column. Iffalse, no filter row is added. -
Added
filter_hideFiltersoption which whentruewill hide the filter row initially. The rows is revealed by hovering over the filter row or giving any filter input/select focus. -
Added
filter_resetoption which will contain a jQuery selector pointing to a reset element (button or link). -
Added
filter_useParsedDataoption- When
true, ALL filter searches will only use parsed data. - To only use parsed data in specific columns, set this option to
falseand use any of the following methods (they all do the same thing), in order of priority:- jQuery data
data-filter="parsed". - metadata
class="{ filter: 'parsed'}". This requires the metadata plugin. - headers option
headers : { 0 : { filter : 'parsed' } }. - header class name
class="filter-parsed".
- jQuery data
- Remember that parsed data most likely doesn't match the actual table cell text,
20%becomes20andJan 1, 2013 12:01 AMbecomes1357020060000. - Enhancement request from issue #96.
- When
-
Added a method to apply a filter to the table when
filter_columnFiltersisfalseby triggering a search on the table.// search using an array - the index of the array matches the column index // [ column0, column1, column2, ..., columnN ] var columns = []; // undefined array elements are treated as an empty search '' columns[4] = '2?%'; // is equivalent to defining the array this way [ '', '', '', '2?%' ] $('table').trigger('search', [columns]);
-
Added "filterInit" triggered event on the table after the filter widget has finished initializing.
-
Added "filterStart" triggered event on the table. Enhancement request from issue #108.
-
Added "filterEnd" triggered event on the table. This is used by the updated pager plugin to allow it to work with the filter widget. Enhancement request from issue #108.
-
Modified filter select dropowns (still added by using
filter-selector setting afilter_functionscolumn totrue):- By default the select will filter exact matches. To only match column content, add a "filter-match" class to the column. Fixes issue #102.
- The contents of the select are now alphanumerically sorted. Fixes issue #103.
-
The filter widget should properly target columns when multiple header rows with column and row spans are included. Fixes issue #113.
-
Added a remove function method.
-
-
Resizable widget update
- Added an option
resizetowidgetOptions- When
falsethe resized columns widths will not save to storage (localStorage/cookie). - Default is
truewhich saves resized column widths.
- When
- Modified the resize method to smooth out the resizing.
- Right clicking (opening the context menu) on the header will now reset the resizing of the columns. If you right-click on the header with no resized columns, the context menu will open as it normally does.
- Added a remove function method.
- Added an option
-
saveSort widget update
- Added an option
saveSorttowidgetOptions- When
falsethe saved sort in storage (localStorage/cookie) will still apply to the table upon initialization, but any new sorts will not save. - Default is
truewhich loads the saved sort on initialization and saves, and overwrites, any new sorts of the table. - Added a remove function method which only clears the saved sort.
- When
- Added an option
-
Sticky Headers Widget update
- This widget now clones the entire thead for stickyfying ( yes, I know that isn't a real word :P ). This is a similar method used by jmosbech in his StickyTableHeaders plugin.
- Header rows containing column and row spans should now correctly align.
- Attempted to correct the border spacing issue in non-webkit browsers. It's not perfect, so this may be tweaked in the future to make it pixel perfect, if that is ever possible.
- Added a remove function method.
-
UITheme widget updated to be more generalized:
-
This widget will now apply a jQuery UI or Bootstrap theme. It was designed to me extendable to other platforms.
-
Added a Bootstrap theme demo. This demo also includes the filter widget with the pager plugin to show their interaction and other styling possibilities.
-
To extend the uitheme widget to other platforms, add/extend the theme in the
$.tablesorter.themesvariable contained in the jquery.tablesorter.widgets.js file. -
To add either a jQuery UI or Bootstrap theme to the table, set it up as follows (also see the jQuery UI or Bootstrap demo):
$("table").tablesorter({ // widget code now contained in the jquery.tablesorter.widgets.js file widgets : [ 'uitheme', 'zebra' ], widgetOptions : { // set the uitheme widget to use the jQuery UI theme class names ## NEW ## uitheme : 'jui' // or 'bootstrap' } });
- The
widgetsoption must include theuithemewidget. - The
widgetOptionsforuithemenow only contains the name of the platform to use (previously it was the 3 icon class names to use). For now, use eitherjuifor jQuery UI orbootstrapfor a Twitter Bootstrap theme.
- The
-
I am working on changing tablesorter's core to do all of this automatically, so if it works out it will be available in tablesorter version 3 and this widget will be obsolete.
-
Bootstrap theme enhancement requested in issue #104.
-
Added a remove function method.
-
-
Zebra widget updates:
- It will no longer apply to nested tables. Fix for issue #98 and also fixed by styson in issue #116. Thanks!
- The zebra widget is needed if using the bootstrap striped theme. See the Bootstrap demo for an example. Fixes issue #111.
- The tbody is no longer hidden (or removed) when applying row class names. It appears to not change the speed significantly. But please feel free to report any speed issues.
- Added a remove function method.
-
Pager addon changes:
- The pager plugin now plays nice with the filter widget.
Fixes issue #6.
- Added
cssGotooption which contains a jQuery selector pointing to a page select dropdown. Updated the pager demo with an example. - Updated pager addong to now work with the filter and advanced filter widgets.
- Added
{filteredRows}and{filteredPages}parameters to theoutputoption. They contain the number of rows and pages that result from the filter widget search.
-
Updated the
jquery.metadata.jsfile to the latest version and modified the code to better work with JSHint.
