Example

This is an example of a small sortable table.

{| class="wikitable sortable"
|-
! name
! data
! more data
|-
| cats
| 273
| 53
|-
| dogs
| 65
| 8,492
|-
| mice
| 1,649
| 548
|}

Tables with complex headers

Tables with more complex headers than before now sort correctly. For example:

{| class="wikitable sortable"
|-
! rowspan=2 | name
! colspan=2 | data columns
|-
! data
! more data
|-
| cats
| 273
| 53
|-
| dogs
| 65
| 8,492
|-
| mice
| 1,649
| 548
|}

Using two or more header rows, the sort arrows are placed on the bottom header row by default. They can be placed a maximum of one row higher by setting class="sorttop" at the top of the bottom header row.

{| class="wikitable sortable"
|-
! column 1
! column 2
|-
! style="text-align:left;" | 3
! style="text-align:left;" | 7
|-
| 1
| 3
|-
| 2
| 4
|}

{| class="wikitable sortable"
|-
! column 1
! column 2
|- class="sorttop"
! style="text-align:left;" | 3
! style="text-align:left;" | 7
|-
| 1
| 3
|-
| 2
| 4
|}

Tables with complex data rows

Tables can have cells spanning multiple rows, using |rowspan=n. (See Help:Rowspan).

The number of rows must be indicated with each use of rowspan. Before any sorting can be done, the rowspan setup must be correct. The wikitext must be correct. An incorrect rowspan organization can break sorting, cause weird table formatting, move data to the wrong column, etc.

See examples below.

When sorted all the rows are filled. Tables without rowspan are much easier to maintain by less experienced editors, and by editors who are stopping by only once to edit the table.

Correct rowspan numbers and wikitext, with sorting in working order:

{| class="wikitable sortable"
|-
! name
! data
! year
|-
| cats
| 273
| 2013
|-
| dogs
| 65
| rowspan=2 | 2014
|-
| mice
| 1,649
<!--column 3 spanned by cell "2014"-->
|}

Note that, after sorting, the rowspanning cells are cut into rows and their content is repeated (the year "2014" in the example). If the original order of a table is restored by clicking a third time on the same arrow, then the cells will remain repeated and not revert to the original rowspan.

See example below. The wikitext is incorrect. Line 17 should not exist. Compare to correct table above. Result in this case is an added empty column.

{| class="wikitable sortable"
|-
! name
! data
! year
|-
| cats
| 273
| 2013
|-
| dogs
| 65
| rowspan=2 | 2014
|-
| mice
| 1,649
|
|}

Secondary key

If a column contains a value multiple times then sorting the column preserves the order of the rows within each subset that has the same value in that column (stable sorting). Thus sorting based on a primary, secondary, tertiary, etc. key can be done by sorting the least-significant key first, etc. For example, to sort the table below on the Text column, then the Numbers column, first click on the "Numbers" column heading (the secondary sort key), then the "Text" column heading (the primary sort key).

Another way to sort a table using multiple sort keys is to hold down the shift key while clicking on the column headings for the subsequent sort keys. For example, to sort the table below on the Text column, then the Numbers column, first click on the "Text" column heading (the primary sort key), then hold down the shift key and click on the "Numbers" column heading (the secondary sort key).

There can be a problem if the Google translation gadget is enabled in gadget preferences (in browsing section). It may seem like shift-click secondary sorting is not working because of the delay due to the translation popup for the name in the column head. There are many browser translation addons that work as well or better than the gadget. The gadget can be turned on and off from the "More" menu at the top of any page.

Vertical headers

{| class="wikitable sortable"
|-
! {{vert header|stp=1|name}}
! {{vert header|stp=1|data}}
! {{vert header|stp=1|more data}}
! {{vert header|stp=1|another column}}
|-
| cats
| 273
| 53
| 1
|-
| dogs
| 65
| 8,492
| 2
|-
| mice
| 1,649
| 548
| 3
|}

This template also works with headers that span rows or columns (using rowspan and colspan). Note that there is no vertical bar | between rowspan=2 and {{vert header

{| class="wikitable sortable"
|-
! rowspan=2 {{vert header|stp=1|name}}
! colspan=2 {{vert header|data columns}}
! rowspan=2 {{vert header|stp=1|another column}}
|-
! {{vert header|stp=1|data}}
! {{vert header|stp=1|more data}}
|-
| cats
| 273
| 53
| 1
|-
| dogs
| 65
| 8,492
| 2
|-
| mice
| 1,649
| 548
| 3
|}

Simple example

This is the wikisource of the table shown in the first section and shows the typical way to enable table sorting:

{| class="wikitable sortable"
|-
! name
! data
! more data
|-
| cats
| 273
| 53
|-
| dogs
| 65
| 8,492
|-
| mice
| 1,649
| 548
|}

The ! indicates cells that are header cells. In order for a table to be sortable, the first row(s) of a table need to be entirely made up out of these header cells. You can learn more about the basic table syntax by taking the Introduction to tables.

Initial sort order of rows

When users are first presented with a table, the rows will always appear in the same order as in the wikitext. If you want a table to appear sorted by a certain column, you must sort the wikitext itself in that order. This is usually done for the first column. The VisualEditor makes it easy to move individual table columns and rows around. For info about that, and also about putting a table in initial alphabetical order see § Initial alphabetical order.

Making selected columns unsortable

If you want a specific column not to be sortable, specify class=unsortable in the attributes of its header cell. If you have a sorting row then class=unsortable must be in the header cell with the sorting icon.

(When using {{vert header}}, disable column sorting by omitting |stp=1 in that template, which overrides anything placed before it.)

{|class="wikitable sortable"
!Numbers!! class="unsortable" |Unsortable
|-
|1||This
|-
|2||Column
|-
|3||Is
|-
|4||Unsortable
|-
|5||See?
|-
!Total: 15!!
|}

Excluding final rows from sorting

Sometimes it is helpful to exclude the last row of a table from the sorting process. There are two methods to achieve this.

{|class="wikitable sortable"
|+ Header as footer example
|-
!scope=col| Name
!scope=col| Surname
!scope=col| Height
|-
!scope=row| John
| Smith
| 1.85
|-
!scope=row| Ron
| Ray
| 1.89
|-
!scope=row| Mario
| Bianchi
| 1.72
|-
!scope=col| Name
!scope=col| Surname
!scope=col| Height
|}

{|class="wikitable sortable"
|+ Summation footer example
|-
!scope=col| Name
!scope=col| Surname
!scope=col| Height
|-
!scope=row| John
| Smith
| 1.85
|-
!scope=row| Ron
| Ray
| 1.89
|-
!scope=row| Mario
| Bianchi
| 1.72
|- class=sortbottom
!scope=row colspan=2 | Average:||1.82
|}

Excluding top rows from sorting

This works the same as above for plain (non-header) rows at the top. This can be achieved using class="sorttop" on the desired table row (line starting with |-). It is possible to keep multiple lines fixed at the top, as long as the lines are consecutive.

data-sort-type=text

data-sort-type=text uses alphabetical sorting of text, but numbers are sorted numerically within that alphabetical sorting. See natural sort order.

For example:

{| class="wikitable sortable"
|-
! Album
|-
 ... etc ...
|}

{| class="wikitable sortable"
|-
! data-sort-type=text | Album
|-
 ... etc ...
|}

Without data-sort-type=text in the header, the tablesorter gets confused by the numeric titles in the first few rows into treating the entire column as numeric. This results in it wrongly sorting the non-numeric titles as zero regardless of the alphabetical ordering of their text.

Note that if a column without declared sort-type contains only numeric values within the first top 5 cells, but with a reference <ref>...</ref> immediately after the last digit of at least one number in those first 5 cells, this may cause the column to be sorted as text. This can be avoided by declaring a different sort type such as: data-sort-type=number

Default data type of a column

If you do not specify a data-sort-type, the sort modes (the data types, which, in addition to the choice "ascending" or "descending", determine the sorting order) are as follows:

date (see also below)

• criterion: the first non-blank element is of the form "DD-MM-YYYY", "DD-MM-YY", or "DD mmm YYYY"
• order: numeric value of YYYYMMDD; The string DDsMMsYYYY of length 10 (if characters positioned at s are equal together and are either '/' or '-' separator) is positioned as YYYYMMDD, the string DDsMMsYY of length 8 (if characters positioned at s are equal together and are either '/' or '-' separator) as 19YYMMDD if YY >= 50 and 20YYMMDD otherwise, and the string "DD mmm YYYY" with mmm an (abbreviated) month name.

isoDate (ISO 8601)

• criterion: format "±YYYY-MM-DD", with 1-4 digits for year "YYYY" from -9999 to 9999, month only with digits, format "±YYYY-MM-DDThh:mm:ss.sss±TH:TM" with time hour "hh", minutes "mm", seconds "ss.sss", and time zone offset "TH:TM, right values are optional.
• order: numeric, with time in milliseconds after 01 January, 1970 UTC.

currency (this mode can be useful for other data also)

• criterion: the first non-blank element starts with $, £, €, or ¥
• order: numeric, ignoring these symbols and all ordinary letters and commas, but not spaces; note that scientific notation cannot be used, as e and E are removed

number

• criterion: the first non-blank element consists of just digits, points, commas, spaces, "+", "-", possibly followed by "e" or "E" and a string consisting of "+", "-", digits
• order: after removing the commas and spaces, if any, if the string starts with a number the order is numeric according to the first number in the string (parseFloat is applied); it is regarded as zero if it is empty; in other cases (parseFloat returns NaN), the element is positioned like -∞.

string

• criterion: all other cases;
• order: uses locale specific (so in this case English) ordering if your browser supports it. Alternatively after conversion of capitals to lowercase the order is ASCII – partial list showing the order: !"#$%&'()*+,-./09:;<=>?@[\]^_'az{|}~é— (see also below; a blank space comes before every other character; a non-breaking space code   counts as a space; two adjacent ordinary blank spaces count as one; for multiple blank spaces one can use   or alternate   and ordinary blank spaces)

If more than one possible type matches, the first type in the above order is chosen. For example, "24-12-2007" matches as a date, so is not treated as a number. Formatting and markup tags are ignored when determining the matching type.

The sort mode is determined by the first 5 non-blank rows below the header after loading the page. This can also change after deleting a row, or adding a column. Therefore, it is wise to make sure that every element matches the criterion for the required data type. Using a row template this can be done very conveniently.

The method of making sure the sort mode of each column is as desired, is specify a data-sort-type, see up.

Keeping some rows together

data-sort-value can be used to keep certain rows together. The specified order of these rows is preserved. An example is to keep "South Holland" immediately after "Netherlands", whatever the sort order or column:

{|class="wikitable sortable"
!Country/province !!Capital
|-
|France ||Paris
|-
|Netherlands ||Amsterdam
|-
|data-sort-value=Netherlands |South Holland ||data-sort-value=Amsterdam |The Hague
|-
|UK||London
|}

If you have rows that contain colspans, this might become a little difficult. You can also use the class="expand-child" on a row; it will then always be below the row just above it in the table source, wherever that row may be sorted in the table.

{| class="wikitable sortable"
!style="width:9.3em" |Country !!Capital
|-
|'''France'''
|Paris
|- class="expand-child"
| colspan="2" | In Paris is the Eiffel Tower.
|-
|'''UK'''
|London
|- class="expand-child"
| colspan="2" | In the U.K. you cannot pay with euros,
|- class="expand-child"
| colspan="2" | and you drive on the left.
|-
|'''Germany'''
|Berlin
|- class="expand-child"
|colspan="2" | Germany includes the former DDR.
|}

c. for circa

"c." (circa, indicates "approximately") is often found in columns of numbers and dates. It often breaks sorting. The addition of data-sort-type="..." to the column header does not allow c. to be put in front of the number.

Using the {{circa}} template fixes sorting when c. is in front of the number, but only if the sortable=yes parameter is added to the template. See: Template:Circa/doc/sortable.

{{circa|NUMBER|sortable=yes}}

NUMBER c. NUMBER

Alternatively, c. can be put after the number. Or it can be moved to a different column.

Numerical ranges

Note: Most problems are fixed by adding data-sort-type=number to the column header. It also prevents problems caused by later editing.

A dash after a number no longer breaks default numerical sorting of a column. Therefore, a range (30–40) now works.

A plus sign after a number breaks default numerical sorting if it is in one of the first 5 cells in a column.

A plus sign in an otherwise empty cell breaks default numerical sorting of a column. That is if the cell is one of the first 5 cells in the column.

You can also use 2 columns for a range if you want to sort by either the lower or upper range. If you want the upper range to sort best all cells need to be filled in with numbers. For example, you can use the same number in both the lower and upper range. You can also add a plus sign after the number in the upper range.

The first set of tables below do not sort correctly, except for the lower range which has no complicating factors. Note that "400+" and "400 +" do not sort correctly in their columns. These tables do not have data-sort-type=number in their column headers.

data-sort-type=number has fixed the sorting in the tables below. Note the sorting of 400+ and 400 +.

Month names

All sorting involving month names may fail for registered users who have changed the default language setting "en - English" at Special:Preferences (reported at phab:T126744). It affects relatively few users on the English Wikipedia and can be ignored.

Year only

Year sorting of a column works as long as the year is the first text in each cell in the column. Adding data-sort-type=date to the column header does not change this.

Text is OK after a year in a cell. "FY" (fiscal year), for example, should go after the year. References after the year are OK. Put "c." after the year, or use "est." after the year instead.

A dash, of any kind, in a blank cell breaks year sorting of a column. Dashes after the year are OK.

Unlike for numerical sorting the {{N/A}} template in any cell in a year column does not break year sorting of that column.

If there are problems with year sorting check for any cells in the column with text or a dash (of any kind) as the first thing in a cell. Remove that text or dash, and the column should sort correctly.

Year and month

Date sorting does not work for columns with only the year before the month (no day).

Adding data-sort-type=date or data-sort-type=isoDate to the column header does not help. Click each column header a couple times in the tables below to see. Note the column headed data-sort-type=isoDate may sort correctly in some browsers, but it is not reliable.
Year and month in numerical form (YYYY-MM) works with data-sort-type=isoDate (see relevant section farther down).

Month and year

Date sorting does not work for columns with only the month before the year (no day). Adding data-sort-type=date to the column header does not help.

Month, day, and year

Sorting works correctly in all the tables below. Years before 100 (for example, year 99) break sorting. If a number for a day is missing, sorting is broken.

Day, month, and year

Sorting works correctly in all cases below. Years before 100 (for example, year 99) break sorting. If a number for a day is missing, sorting is broken.

Year, month, day. Using words for months

Sorting does not work for this date order.

data-sort-type=date

data-sort-type=isoDate

The addition of any data-sort-type to the column header does not help. See examples below.

Year, month, day. Using numbers. ISO date YYYY-MM-DD

See: ISO date. "±YYYY-MM-DD", with 1 to 4 digits for year "YYYY" from -9999 to 9999. Year by itself is fine. As is the year followed by just the month. Some stuff after the date is allowed. Such as references after the date. To save header space you can add a tooltip to the "Date" column header instead of "year, month, day" below it. See: Template:Tooltip. Tooltips have been added to the tables in this section.

See section higher up: #Examples of datatype auto detection. First 5 cells in a column. Datatype auto detection is inconsistent. That is why ISO date sorting works best with data-sort-type=isoDate added to the column header. It also avoids problems when only one digit is used for the month or day. Leading zeros are no longer needed. All tables below have data-sort-type=isoDate added to the column headers.

Remember to leave a space in the wikitext before years that are a negative number. Otherwise, |- will be used as table formatting instead of |.

"c." stands for circa (approximately). "c." before the date breaks sorting in the first table. Using the {{circa}} template fixes sorting, but only if the sortable=yes parameter is added to the template. See: Template:Circa/doc/sortable. See: #c. for circa.

{| class="wikitable sortable"
|-
! data-sort-type=isoDate |{{Tooltip|Date|Year, month, day}}<br><small>{{tl|circa}} used.<br>Sorting works.</small>
|-
| -90
|-
| {{circa|sortable=yes|90}}
|-
| 90-7-13
|-
| 90-12-5
|-
| 1011-08-01<sup style="color:gray">[2]</sup>
|-
| {{circa|sortable=yes|207-11}}<sup style="color:gray">[1]</sup>
|}

Adding BCE, CE, BC, etc. after the date does not break sorting. But adding AD before the date breaks sorting. Test additions before and after dates. Additions before the date are almost always a problem.

Issues. Years BC, etc

For years BC, !9937-09-23 can be used for -0062-09-23 (62 BC): Simply subtract the year BC from 10,000.

• See also: bugzilla:8226

Date sorting works by formatting dates so they can be sorted numerically. For example:

• yyyy mm dd

or

• 2001 07 21

...for 21 July 2001. The display:none style can be used to hide a sortable numeric date before the displayed date. See wikitext of table just below. Alternatively, {{Date table sorting}} does this automatically, and is recommended in most cases.

You can use July 7, 2012 etc. to get sortable dates. Example, including one date with a different display format:

{| class="wikitable sortable"
|-
! Date
|-
| {{dts|2012-01-07}}
|-
| {{dts|2012-05-07}}
|-
| {{dts|4 July 2012}}  <!-- Ensure alternate display date format works -->
|-
| {{dts|2012-07-07}}
|}

Padding

Sometimes entries are padded on the left for alignment purposes. This can adversely affect how they are sorted.

Controlling sorting and display

Text undesired for sorting but needed for display:

• In numeric sorting mode, text breaks numerical sorting whether the text is before or after the number. Sorting then becomes alphanumeric. Empty cell is treated as "zero" when sorting numerically.
• In date sorting mode, this text needs to be put in a separate column; in the case of a cell containing a range of dates or numbers (e.g. from .. to ..), text in surplus of what is required for sorting is put in the extra column. If the first part of the text is used for sorting, then the extra column needs to be the following one; conversely, if the last part of the text is used for sorting, then the extra column needs to be the previous one; depending on the table format, this dividing of an item over two cells may look ugly.
• In alphabetic sorting, any footnotes etc. do not require a separate column; they can simply be put at the end of the element.

Text undesired for display but needed for sorting:

• can be put as hidden text in the column to be sorted

Combining the two, we can have displayed text independent of text used for sorting, by fully hiding the latter, and fully putting the former in a separate column (in date sorting mode and numeric sorting mode) or in the same column after the hidden text (in alphabetic sorting). Fully putting the displayed text in a separate column may look ugly if it is not done consistently for a whole column, but only for elements that require this (e.g. if most entries in a column are single numbers, but some are ranges).

Sorting with increase/decrease/steady templates

More information Example, Without key ...

Example	Without key	With key
Apple	10	10
Banana	2	2
Cherry	1	1
Durian

Close

To enable sorting of cells with Template:Increase, Template:Decrease or Template:Steady, add a sort key, e.g. {{increase|2}}2, {{decrease|-1}}1 or {{steady|0}}. To fix an existing table, use Search and replace (right icon in the Advanced toolbar) with Treat search string as a regular expression selected to do the following replacements:

Putting a table in initial alphabetical order

There are fast and slow ways to do this. Unfortunately, the Visual Editor does not have a fast way to quickly alphabetize a table. You can manually move rows around one at a time. Click on a cell in a row. Then click on the arrow that shows up at the left of the row. Then click on "move above" or "move below" as needed. If this is buggy or is not working, the rows can be moved around in the wikitext by cutting and pasting rows in the wikitext.

A fast way is to launch free LibreOffice Calc, or another spreadsheet program. To see how go to Help:Table#Sort alphabetically/numerically with spreadsheet & VE. For more info see Commons:Convert tables and charts to wiki code or image files.

There is another way to alphabetize a table, and it keeps all the styling and flag links that a spreadsheet may remove. One can use NoteTab Light (freeware version of NoteTab). But for this to work, all the wikitext for a row must be on one line. That means the cells in that row are separated by double bars ||.

To alphabetize the list by the first column paste the table wikitext into a new NoteTab Light page. Select the rows you want to alphabetize. Then click on the "modify" menu, then "lines", then "sort", and then "ascending". That will put "A" at the top and "Z" at the bottom.

Then put back |- (wikitext for row) between each line. Do that via find-and-replace by replacing ^p with ^p|-^p

^p is the underlying text editor code for line breaks in NoteTab.

|- is the wikitext for a table row.

If there are blank lines between the entries replace ^p^p with ^p|-^p

Copy the wikitext and paste it back into the article. Save the page.

Initial alphabetical sort versus initial sort by rank order

It is a good idea to keep lists and tables in some kind of initial non-random sort order. It no longer matters what method you choose. Template:Static row numbers will maintain row numbering automatically no matter what changes you make to the row order.

Auto-ranking or adding a row numbering column (1,2,3)

There are Phabricator threads asking for a way to easily add static row numbers to tables. See phab:T42618. It supersedes phab:T42634.

In the meantime there is Template:Static row numbers. It is easy to use now. It is a template to automatically add row numbers to sortable tables. The row numbers will not be sorted when columns of data are sorted. A possible note to add above a table: Row numbers are static. Other columns are sortable. This allows ranking of any column.

See list of articles transcluding {{static row numbers}}. See transclusion count.

It has some subtemplates that work with it. Go to {{static row numbers}} for more details.

To see the template in use: List of U.S. states and territories by incarceration and correctional supervision rate.

Note that style=max-width:Xem is selectively used to narrow columns with wordy header text without using breaks <br>. Header breaks annoy people using screen readers due to the pauses.

The selective use of max-width allows the state names to spread out, and stay on one row each if the screen is wide enough. This allows easier scanning down or across the rows. Yet when the screen becomes narrower and narrower, the state names will eventually wrap. This is good for cell phones. Use em unit settings instead of px. Em units expand in width as the font size is increased.

Be sure to check both mobile and desktop views (links at bottom of page). Check to see that header rows aren't being given a row number. Also check that the max-width settings aren't too tight. Mobile view may need a slightly larger max-width setting for some columns. And different desktop browsers, and different settings for them, can make some max-width settings cause some column header text to overlap into the adjacent column. So it is usually good to add some extra em units to the max-width settings.