Tablesorter is a powerful jQuery plugin that provides sophisticated sorting functionality for HTML tables. It allows you to easily add client-side sorting capabilities to your tables, enabling users to interactively sort table rows based on the data within individual columns. This enhances the usability of your tables, making it easier for users to find and analyze data. Unlike server-side sorting, Tablesorter performs sorting directly in the user’s browser, resulting in faster response times and reduced server load.
Tablesorter is designed to work across a wide range of modern web browsers. While it aims for broad compatibility, optimal performance and feature support are best achieved with modern, up-to-date browsers. For optimal results, we recommend using the latest versions of:
Older browsers might exhibit limited support or require additional configuration. Thorough testing across your target browsers is always recommended.
Include jQuery: Tablesorter relies on jQuery. Ensure you have included the jQuery library in your HTML file before including the Tablesorter plugin. You can download jQuery from https://jquery.com/ or use a CDN link:
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>Include Tablesorter: Download the Tablesorter plugin files (typically jquery.tablesorter.js and jquery.tablesorter.widgets.js) and include them in your HTML after the jQuery inclusion:
html <script src="jquery.tablesorter.js"></script> <script src="jquery.tablesorter.widgets.js"></script> Alternatively, use a CDN link if available.
Initialize Tablesorter: Select your table element using a jQuery selector and call the tablesorter() method.
<table id="myTable">
<thead>
<tr>
<th>Column 1</th>
<th>Column 2</th>
</tr>
</thead>
<tbody>
<tr><td>Data 1</td><td>Data 2</td></tr>
<tr><td>Data 3</td><td>Data 4</td></tr>
</tbody>
</table>
<script>
$(document).ready(function() {
$("#myTable").tablesorter();
});
</script>This basic setup will enable sorting on all columns. For more advanced configurations (e.g., specifying sorting types, using widgets), refer to the detailed documentation and examples provided with the plugin.
The simplest way to initialize Tablesorter is by including the necessary JavaScript files (as described in the “Getting Started” section) and then calling the tablesorter() method on your table element using a jQuery selector. This will automatically enable sorting on all columns based on their data type.
$(document).ready(function() {
$("#myTable").tablesorter();
});Replace "#myTable" with the appropriate jQuery selector for your table. This code should be placed within a $(document).ready() function to ensure the DOM is fully loaded before initializing the plugin.
Tablesorter provides several options to customize its behavior. These options are passed as a JavaScript object to the tablesorter() method. Some key options include:
theme: Specifies the CSS theme to use (e.g., “blue”, “bootstrap”).headers: An array specifying which columns are sortable (true/false) and their sorting type.sortList: An array defining the initial sorting order (e.g., [[0,0], [1,1]] sorts the first column ascending and the second column ascending).widgets: An array of widgets to enable (e.g., [‘filter’, ‘zebra’]).$(document).ready(function() {
$("#myTable").tablesorter({
theme: "blue",
headers: {
0: { sorter: false }, // Disable sorting for the first column
1: { sorter: 'currency' } //Use currency sorter for the second column
},
sortList: [[1,1]] //Sort second column ascending initially
});
});By default, Tablesorter attempts to intelligently determine the data type of each column and applies the appropriate sorting algorithm. It uses a series of built-in parsers to handle common data types like numbers, dates, and strings. For numeric and date columns, sorting is typically handled correctly without any additional configuration. String columns are sorted lexicographically (case-insensitive by default).
You can customize the sorting behavior for specific columns using the headers option. This allows you to specify a custom sorting function or use a predefined sorter.
$(document).ready(function() {
$("#myTable").tablesorter({
headers: {
2: { sorter: 'text' } //Case-sensitive text sorting for column 3
}
});
});To define a completely custom sorting function, you provide a function that takes two arguments (the values to compare) and returns -1, 0, or 1 depending on the sort order.
$(document).ready(function() {
$("#myTable").tablesorter({
headers: {
3: { sorter: function(a, b) {
// Custom sorting logic here
return a.localeCompare(b);
}
}
}
});
});You can control which columns are sortable and modify their header appearance using the headers option. Setting a header’s sorter property to false disables sorting for that column. You can also use CSS to style the headers. Tablesorter adds classes to the header cells to indicate the sort order (e.g., headerSortUp, headerSortDown, headerSort).
Tablesorter includes built-in parsers to automatically handle various data types. These parsers ensure correct sorting for numbers, dates, currencies, and more. However, for complex or unusual data types, you may need to create custom parsers. The plugin documentation provides details on creating and registering custom parsers. Common data types are typically handled correctly without explicit parser configuration.
Tablesorter can be used on multiple tables on a single page. Simply call the tablesorter() method on each table element using its appropriate jQuery selector. Ensure that each table has a unique ID or class for proper selection.
$(document).ready(function() {
$("#table1").tablesorter();
$("#table2").tablesorter();
});Tablesorter directly supports sorting only on the outermost tables. Nested tables (tables within table cells) will not be sorted by the plugin. To handle nested tables, you would need to implement a custom solution, potentially involving iterating through the nested tables and applying sorting logic individually.
Users can sort by multiple columns simultaneously by clicking on the column headers. The order in which columns are clicked determines the sort order. To specify an initial multi-column sort order, use the sortList option:
$(document).ready(function() {
$("#myTable").tablesorter({
sortList: [[0, 1], [1, 0]] //Sort column 1 ascending, then column 2 descending
});
});This initializes the table sorted by column 1 ascending and then column 2 descending.
The filter widget allows users to filter table rows based on the text content of each cell. Enable the widget by including it in the widgets option:
$(document).ready(function() {
$("#myTable").tablesorter({
widgets: ["filter"]
});
});This adds a filter input field above each column header, allowing users to filter rows based on the column contents. Consult the Tablesorter documentation for details on widget options and customization.
The pager widget provides pagination functionality for large tables. Enable the widget similarly to the filter:
$(document).ready(function() {
$("#myTable").tablesorter({
widgets: ["pager"]
});
});You will also need to include appropriate HTML elements (e.g., for page navigation) as described in the plugin’s documentation.
Tablesorter’s functionality is greatly extended by widgets. Widgets add features like filtering, pagination, and styling enhancements. Enable widgets by including their names in the widgets option array. See the plugin’s documentation for a complete list of available widgets and their configurations.
For data types not automatically handled by the built-in parsers, you can create custom parser functions. These functions define how data in a column should be interpreted for sorting. Refer to the Tablesorter documentation for details on creating and registering custom parsers. This involves defining a function that takes a cell’s content as input and returns a value suitable for comparison.
Tablesorter supports various CSS themes to customize the table’s appearance. Select a theme using the theme option:
$(document).ready(function() {
$("#myTable").tablesorter({
theme: "bootstrap" // or "blue", "jui", etc.
});
});You’ll need the corresponding theme CSS file included in your project.
Ensure your tables are accessible by following accessibility best practices. Use appropriate ARIA attributes (like aria-sort on headers) to improve screen reader compatibility. Tablesorter generally supports accessibility features, but proper implementation of ARIA attributes and semantic HTML is crucial.
For internationalization support (handling different languages and locales), you might need to use a suitable date/time library and potentially create custom parsers to handle locale-specific date and number formats. Consider using the localeCompare method for string comparisons to handle language-specific sorting. The plugin itself doesn’t include built-in internationalization features beyond the default capabilities of JavaScript’s built-in functions.
Tablesorter exposes several methods for interacting with the plugin after initialization. These methods are called on the jQuery object representing the table. Some key methods include:
destroy(): Removes Tablesorter functionality from the table and restores the table to its original state.addRows(rows, [update]): Adds new rows to the table. The rows argument is an array of rows (each row can be a string of HTML or a jQuery object). The optional update argument (boolean) indicates whether to update the table’s sorting after adding rows.update(): Re-initializes the sorting for the table. Useful after adding, removing, or modifying rows.sortOn(column, order): Programmatically sorts the table by a specified column and order. column is the column index (0-based), and order is 0 for ascending and 1 for descending.getSortList(): Returns the current sort order as an array.setHeaderFilter(value, column): Sets the filter value for a specified column. Useful for programmatic filtering.Example:
$("#myTable").tablesorter().tablesorter("addRows", [ "<tr><td>New Row 1</td><td>Data</td></tr>" ]);
$("#myTable").tablesorter("sortOn", 0, 0); //Sort the first column ascending
let sortOrder = $("#myTable").tablesorter("getSortList");
console.log(sortOrder); // Output current sort orderConsult the full Tablesorter documentation for a complete list of available methods and their parameters.
Tablesorter triggers several events throughout its lifecycle. These events can be used to perform custom actions based on sorting or other plugin operations. These are jQuery events, so you can use jQuery’s on() method to listen for them. Some important events include:
sortBegin: Triggered before the sorting process begins.sortEnd: Triggered after the sorting process is complete.pagerComplete: Triggered after the pager widget completes pagination (if the pager widget is enabled).filterStart: Triggered when filtering starts (filter widget).filterEnd: Triggered when filtering completes (filter widget).Example:
$("#myTable").on("sortEnd", function(e, table) {
console.log("Sorting complete!");
});The options passed to the tablesorter() method control various aspects of the plugin’s behavior. These options were discussed partially in the Basic Usage and Advanced Usage sections. Refer to the full Tablesorter documentation for the complete list of options and their descriptions. Options are key-value pairs within a JavaScript object. Some of the commonly used options were already illustrated previously (e.g., theme, headers, widgets, sortList).
Tablesorter doesn’t expose many public properties directly accessible from outside the plugin. Information like the current sort order is usually accessed using methods like getSortList(). The plugin’s internal data structure is not intended for direct manipulation. The primary way to interact with the plugin is through its methods and events. Avoid directly accessing or modifying internal plugin properties, as this might break functionality and is not supported.
This section addresses frequently encountered problems when using Tablesorter.
tablesorter() method is called correctly within a $(document).ready() function.headers option to specify custom sorters for specific columns (see the “Customizing Sorting” section).jquery.tablesorter.widgets.js) are included.widgets option array.Browser Developer Tools: Use your browser’s developer tools (usually accessed by pressing F12) to inspect the HTML, CSS, and JavaScript. Check the console for errors and warnings. Use the network tab to ensure that all necessary files are loaded correctly.
Console Logging: Add console.log() statements to your JavaScript code to track variable values and the execution flow. This helps pinpoint errors in your initialization code or custom functions.
Simplified Test Cases: If you are encountering issues with complex tables, try creating a simplified test case with minimal data and features. This isolates the problem and makes it easier to debug.
jQuery Debugging: If you suspect jQuery-related issues, use jQuery’s debugging tools or add console.log statements to trace jQuery’s behavior in your code.
Check the Tablesorter Documentation: Thoroughly read the official Tablesorter documentation for detailed explanations of options, methods, and usage instructions. The documentation often provides troubleshooting information for common problems.
Tablesorter generally doesn’t throw many custom error messages. Most errors will manifest as JavaScript errors in your browser’s console (e.g., “Uncaught TypeError,” “Uncaught ReferenceError”). These errors will usually indicate problems with the inclusion of necessary files, incorrect use of the API, or conflicts with other JavaScript libraries.
Examine the error messages in your browser’s console carefully. They usually provide clues to the source and nature of the problem, including the line number of the problematic code. If the error message is unclear, try the debugging tips described above to pinpoint the cause. If you are unable to resolve the issue, check the Tablesorter’s issue tracker or community forums for assistance.
We welcome contributions to Tablesorter! Whether you’re fixing bugs, adding features, or improving the documentation, your help is valuable. Here’s how you can contribute:
Before submitting a new issue, please check if a similar issue already exists. Search the issue tracker to see if someone has reported the same or a related problem.
When reporting a new issue, please provide the following information:
Fork the repository: Create a fork of the official Tablesorter repository on GitHub.
Create a new branch: Create a new branch for your changes. Use a descriptive branch name that reflects the changes you’re making (e.g., “fix-bug-123,” “add-feature-xyz”).
Make your changes: Make your code changes, ensuring they adhere to the coding style guidelines (see below). Thoroughly test your changes before submitting the pull request.
Commit your changes: Commit your changes with clear and concise commit messages.
Push your branch: Push your branch to your forked repository.
Create a pull request: Create a pull request on GitHub, linking your branch to the main repository’s branch. Provide a clear description of your changes in the pull request.
To maintain consistency and readability, please adhere to the following coding style guidelines when contributing to Tablesorter:
Before submitting a pull request, ensure that your code passes all existing tests and follows the coding style guidelines. We may request changes to your code before merging it into the main repository.