View source for Template:Sticky header/doc

{{Documentation subpage}}
{{High-use}}
{{Template redirect|sticky-header}}
{{uses TemplateStyles|Template:Sticky header/styles.css}}

This template makes a table's column headers stick to the top of the screen as the table's data is scrolled in and out of view. It's used on tall tables that have column headers that might be difficult to remember as you scroll through the data.

== Usage ==

Include this template by adding {{tlc|sticky header}} or its redirect {{tlc|sticky-header}} above a table. Add one of the following classes to the table start wikitext.

{| class=wikitable style="background-color: white;"
|+ Classes for table start wikitext: <code><nowiki>{|</nowiki> class="''class1 class2''"</code>.
|-
! Class
! Summary
|-
| class=nowrap | <code>sticky-header</code>
| Make the first header row top sticky.
|-
| class=nowrap | <code>sticky-header-multi</code>
| <strong>Requires sortable table</strong>. Make multiple header rows top sticky. Avoid use with the <code>sorttop</code> class that becomes sticky after sorting. Avoid making headers sticky that aren't for the entire table (ex. section header rows). Avoid making excessively tall header rows sticky that might block too much data on short screens (ex. mobile landscape).
|}

== Single sticky header row ==

The <code>sticky-header</code> class is used to make the first header row top sticky. Sortable is not required.

<div style="display: inline-grid; vertical-align:top;">
{{sticky header}}
{| class="wikitable sortable sticky-header"
|+ Caption
|-
! Color !! A !! B
! class="unsortable" | C
|- class=sorttop
| '''Max''' || 10 || 11 || 12
|-
| Red || 1 || 2 || 3
|-
| Lime || 4 || 5 || 6
|-
| Gold || 7 || 8 || 9
|-
| Blue || 10 || 11 || 12
|- class=sortbottom
| '''Total''' || 22 || 26 || 30
|}
</div>

<div style="display: inline-grid; vertical-align:top;">
<syntaxhighlight lang=wikitext highlight=1-2>
{{sticky header}}
{| class="wikitable sortable sticky-header"
|+ Caption
|-
! Color !! A !! B
! class="unsortable" | C
|- class=sorttop
| '''Max''' || 10 || 11 || 12
|-
| Red || 1 || 2 || 3
|-
| Lime || 4 || 5 || 6
|-
| Gold || 7 || 8 || 9
|-
| Blue || 10 || 11 || 12
|- class=sortbottom
| '''Total''' || 22 || 26 || 30
|}
</syntaxhighlight>
</div>

== Multiple sticky header rows ==

{{Tracked|T6740}}
{{Tracked|T355492}}
The <code>sticky-header-multi</code> class is used to make multiple header rows top sticky. '''Sortable table is required''' since sortable is currently the only way to move consecutive rows of column headers to the {{Tag|thead|o}} element. If some or all columns should not be sortable, then <code>class=unsortable</code> can be put in the header cell with the sorting icon. Table top will still be sticky. See [[Help:Sortable tables]]. If [[JavaScript]] is disabled, then sortable and this solution won't work. 

Avoid using the <code>sorttop</code> class since sortable moves those rows into the {{Tag|thead|o}} element after sorting, which makes them top sticky too. A solution might be to move them to the bottom and use the <code>sortbottom</code> class instead.

<div style="display: inline-grid; vertical-align:top;">
{{sticky header}}
{| class="wikitable sortable sticky-header-multi"
|+ Caption
|-
! rowspan=2 | Color
! colspan=3 | Data
|-
! A !! B
! class="unsortable" | C
|-
| Red || 1 || 2 || 3
|-
| Lime || 4 || 5 || 6
|-
| Gold || 7 || 8 || 9
|-
| Blue || 10 || 11 || 12
|- class=sortbottom
| '''Max''' || 10 || 11 || 12
|- class=sortbottom
| '''Total''' || 22 || 26 || 30
|}
</div>

<div style="display: inline-grid; vertical-align:top;">
<syntaxhighlight lang=wikitext highlight=1-2>
{{sticky header}}
{| class="wikitable sortable sticky-header-multi"
|+ Caption
|-
! rowspan=2 | Color
! colspan=3 | Data
|-
! A !! B
! class="unsortable" | C
|-
| Red || 1 || 2 || 3
|-
| Lime || 4 || 5 || 6
|-
| Gold || 7 || 8 || 9
|-
| Blue || 10 || 11 || 12
|- class=sortbottom
| '''Max''' || 10 || 11 || 12
|- class=sortbottom
| '''Total''' || 22 || 26 || 30
|}
</syntaxhighlight>
</div>

=== Header rows not for whole table ===

Consecutive rows of column headers are top sticky, so avoid adding a row of headers right under the column headers that don't apply to the entire table such as a section header meant to visually separate the table.

A solution might be to move each section to a column or separate tables, which also avoids accessibility issues per [[MOS:COLHEAD]].

Another solution might be to add a blank row of data cells (<code>| colspan=4 |</code>) between the last column header row and the first section header row so the latter is not included in the consecutive header rows.

<div style="display: inline-grid; vertical-align:top;">
{{sticky header}}
{| class="wikitable sortable sticky-header-multi"
|+ Caption
|-
! rowspan=2 | Color
! colspan=3 | Data
|-
! A !! B !! C
|-
| colspan=4 |
|-
! colspan=4 | Section 1
|-
| Red || 1 || 2 || 3
|-
| Lime || 4 || 5 || 6
|-
! colspan=4 | Section 2
|-
| Gold || 7 || 8 || 9
|-
| Blue || 10 || 11 || 12
|}
</div>

<div style="display: inline-grid; vertical-align:top;">
<syntaxhighlight lang=wikitext highlight=1-2,9-10>
{{sticky header}}
{| class="wikitable sortable sticky-header-multi"
|+ Caption
|-
! rowspan=2 | Color
! colspan=3 | Data
|-
! A !! B !! C
|-
| colspan=4 |
|-
! colspan=4 | Section 1
|-
| Red || 1 || 2 || 3
|-
| Lime || 4 || 5 || 6
|-
! colspan=4 | Section 2
|-
| Gold || 7 || 8 || 9
|-
| Blue || 10 || 11 || 12
|}
</syntaxhighlight>
</div>

=== Excessively tall header rows ===

Avoid excessively tall header rows that might block too much or all data when sticky on a small mobile screen, especially in [[Page orientation|landscape orientation]]. Some solutions might be to move some of the header text to the table caption, more concise header text, remove line-breaks ({{Tag|br|o}}) in the headers, or split the table up into smaller tables to reduce headers.

<div style="display: inline-grid; overflow-y: scroll; max-height: 300px;">
{{sticky header}}{{sort under}}
{| class="wikitable sortable sort-under sticky-header-multi" style="margin: 0;"
|-
! colspan=4 | Header<br>group<br>1
|-
! colspan=2 | Header<br>group<br>2
! colspan=2 | Header<br>group<br>3
|-
! Header<br>1 !! Header<br>2 !! Header<br>3 !! Header<br>4
|-
| data || data || data || data
|-
| data || data || data || data
|-
| data || data || data || data
|-
| data || data || data || data
|-
| data || data || data || data
|-
| data || data || data || data
|-
| data || data || data || data
|-
| data || data || data || data
|}
</div>

== Known issues ==

Tested in browsers on [[Windows 10]], [[Windows 11]], [[iOS 17]] ([[iPhone SE (2nd generation)|iphone SE 2020]] and [[iPhone 14 Pro Max|iPhone 14 Pro Max]]), and [[Android 14]] ([[Samsung Galaxy S21]]).

* Does not work on the MonoBook skin when the browser width is 550 pixels or less due to the <code>body.skin--responsive .monobook-body {overflow: auto;}</code> style that can't be overridden.
* On Android phones, table headers aren't top-sticky if at least one table using this template is wider than the screen, which is more likely in [[Page orientation|portrait orientation]]. The table's horizontal scroll doesn't work with this template, so wide tables span outside of the main content area making the entire page wider and requiring you to instead horizontally scroll the entire page. Zooming out to see the entire table makes the headers sticky, but also makes the text smaller and less readable the wider the table is. Currently, the only semi-solution is to view the zoomed out sticky headers in landscape orientation instead of portrait orientation so that the text is more readable.
* <code><nowiki><div style="overflow:auto"></div></nowiki></code> - Do not use this around tables. It prevents sticky headers until removed. See [https://en.wikipedia.org/w/index.php?title=The_Economist_Democracy_Index&diff=1222822979&oldid=1222822630 diff]. See "List by region" table.
* Jumping to an {{tl|Anchor}} (or similar mechanism for creating an anchor) in a table causes that location of the table to be at the top of the screen, where the sticky header covers it. True for all skins except Vector 2022 and MinervaNeue skin (mobile). See discussions [[Template talk:Sticky header#Sticky header covering jump result|here]] and [[Template talk:Sticky header/Archive 1#Headings cover the row when you link an anchor in a table|here]].

== See also ==

* {{slink|Help:Table/Advanced#Tables with sticky headers}}
* {{t|sticky table start}} - allows sticky rows and columns inside a scrollable area.
* {{t|shy}} – Can be used to help narrow columns by adding a [[soft hyphen]] to a word to allow it to wrap.

More [[WP:template styles|template styles]] for tables:
* {{t|sort under}} - moves the sorting arrows under the headers.
* {{t|row hover highlight}} - adds row hover highlighting, and option for white background. 
* {{t|static row numbers}} - adds a column of row numbers to a table.
* {{t|table alignment}} - aligns the cells in a column, or a whole table.

<includeonly>{{Sandbox other||
<!-- Categories below this line; interwikis at Wikidata -->
[[Category:Table templates]]
[[Category:Templates using TemplateStyles to style external elements]]
}}
</includeonly>