Fork me on GitHub

Intro

jquery.floatThead is a floating/locked/sticky table header plugin that requires no special CSS and supports window and overflow scrolling.

Features:

  • Floats the table header - so that the user can always see it
  • Supports tables with inner scroll bars, or window scrolling
  • Horizontal or vertical scrolling
  • Doesn't clone the thead - so your events stay bound
  • Doesn't mess with your styles
  • Works on any table
  • Requires no special css
  • Works with datatables out of the box

Requirements:

  • jQuery 1.8.x or better (code is 1.9+ compliant) or jQuery 1.7.x + jQuery UI core
  • Internet Exploder 8 - 11, FireFox 10+ or Chrome15+
  • Add this meta tag into your header to placate IE: <meta http-equiv="X-UA-Compatible" content="IE=10; IE=9; IE=8; IE=7; IE=EDGE" />

Demo



Header 1 Header 2 Header...3
Cell Content 1 Cell Content 2 Cell Content 3
More Cell Content 1 More Cell Content 2 More Cell Content 3
Even More Cell Content 1 Even More Cell Content 2 Even More Cell Content 3
And Repeat 1 And Repeat 2 And Repeat 3
Cell Content 1 Cell Content 2 Cell Content 3
More Cell Content 1 More Cell Content 2 More Cell Content 3
Even More Cell Content 1 Even More Cell Content 2 Even More Cell Content 3
And Repeat 1 And Repeat 2 And Repeat 3
Cell Content 1 Cell Content 2 Cell Content 3
More Cell Content 1 More Cell Content 2 More Cell Content 3
Even More Cell Content 1 Even More Cell Content 2 Even More Cell Content 3
And Repeat 1 And Repeat 2 And Repeat 3
Cell Content 1 Cell Content 2 Cell Content 3
More Cell Content 1 More Cell Content 2 More Cell Content 3
Even More Cell Content 1 Even More Cell Content 2 Even More Cell Content 3
And Repeat 1 And Repeat 2 And Repeat 3
Cell Content 1 Cell Content 2 Cell Content 3
More Cell Content 1 More Cell Content 2 More Cell Content 3
Even More Cell Content 1 Even More Cell Content 2 Even More Cell Content 3

Usage

There are 2 ways you can initialize the table:

  • Overflow scrolling
    The table is inside of a container with overflow:auto
  • Window scrolling
    Header becomes locked at the top of the page as user scrolls down
Window scrolling is the default. Initialize floatThead without any params to use it. $('table').floatThead()

Overflow scrolling takes a bit more work. You must specify a container element inside of which the table will scroll. You must create this element. Usually a div will wrap the table with overflow:auto and a size smaller than the table.
var $table = $('table.demo');
$table.floatThead({
    scrollContainer: function($table){
		return $table.closest('.wrapper');
	}
});

Options

Note: All the options which are functions take a single argument: $table - the table who's header is being floated.
ex: function($table){ ... }
Name type default description
scrollContainer function null Defines a container element inside of which the table scrolls vertically and/or horizontally. usually a wrapping div
scrollingTop number or function 0 Offset from the top of the window where the floating header will 'stick' when scrolling down
scrollingBottom number or function 0 Offset from the bottom of the window where the floating header will 'stick' when scrolling down
floatTableClass string floatThead-table This class is added to the table element after you run floatThead on it
floatContainerClass string floatThead-container This class is added to the container div inside of which your thead will spend time floating
useAbsolutePositioning boolean true Position the floated header using absolute positioning or using fixed positioning. Fixed positioning performs better with tables that use window scrolling, but fails miserably on highly dynamic pages where DOM can be suddenly modified causing the location of the floated table to shift. (You should call .floatThead('reflow') in this case, but you cant always instrument your code to make that call.)
debounceResizeMs number 1 The headers are repositioned on resize. Because this event has the potential to fire a bunch of times, it is debounced. This is the debounce rate.
zIndex number 1001 z-index of the floating header
headerCellSelector string tr:first>th:visible Specifies the selector used to find header cells (in the table's thead element)
cellTag string null Deprecated! Use headerCellSelector instead. Will be removed in v1.3.0
debug boolean false Point out various possible issues via console.log if it is available
getSizingRow function undefined

Used by IE Only

If your table's first visible row (tbody tr:visible:first>*) contains td or th elements with colspans, then you need to return another set of cells which have no colspans. In other words the selector should return the same number of cells as columns in your table. In depth docs
copyTableClass boolean true Should the table's class attribute be copied to the floated table? This make the styles written for the table's class selector apply also to the floated header. However, if you are later selecting this table by class you may be surprised to find 2 tables.

Methods

.floatThead('destroy')

Removes the widget from the table

var $table = $('table.demo1');
//float the headers
$table.floatThead();
//unfloat the headers
$table.floatThead('destroy');


.floatThead('reflow')

Cause header to realign itself to the correct position. Same as the reflow event below.

var $table = $('table.demo1');
//float the headers
$table.floatThead();
$table.floatThead('reflow');


.floatThead('getRowGroups')

Returns the table's thead, tbody and tfoot elements. Useful because you cannot simply select thead if the table's header is currently being floated.
For more info on why you may want this read through this example

Events

$table.trigger('reflow')

Given a table element $table that has been widgetized, a reflow event causes the header to realign itself to the correct position. This event must be triggered if the DOM is modifed in such a way that the widgetized table's location changes.
var $table = $('table.demo1');
$table.floatThead();
//change the location of the table in the dom:
$table.css('marginTop', 100);
//cause the floated header to be properly positioned again:
$table.trigger('reflow');

Examples

Overflow Scrolling

Overflow scrolling is used when the table is inside of a container smaller than itself with overflow:auto.

This also demonstrates the reflow method. When a DOM modification causes the table's location to change, you must call this method on the table.

var $demo1 = $('table.demo1');
$demo1.floatThead({
	scrollContainer: function($table){
		return $table.closest('.wrapper');
	}
});
$('a#change-dom').click(function(){ //click to remove
	$(this).parent().hide();
	//DOM has changed. must reflow floatThead
	$demo1.floatThead('reflow');
});
There might be some table controls here or something.. Click to remove

Window Scrolling

Window scrolling is used when you have a large table that takes up the whole screen.

$('table.demo2').floatThead({
	useAbsolutePositioning: false
	// absolutePositioning is better for
	// highly dynamic sites
	// (which this is not)
});

Open Issues

Issues are pulled from github There are a bunch of closed issues!


  • There are no issues! I can finally retire!

Common Problems

Can't get the plugin to work on your site?


Take a look at this list of things that will cause the plugin to not work: Ideal HTML structure

Search the issues on github, maybe someone else had the same problem and solved it. There are a bunch of closed issues, so chances are your issue is not a unique snowflake :)

If all else fails, post a new issue on github. Be sure to include a simple, reproducible example of your issue on jsfiddle.

When I help you solve your problem, buy me a coffee!



Download

Download Latest Release:


Inside of that zip the following javascript files are of interest to you:

  • /dist/jquery.floatThead.js = development version
  • /dist/jquery.floatThead.min.js = production version

if your project includes underscore and you want to save a few bytes you can use the slim version:

  • /dist/jquery.floatThead-slim.js
  • /dist/jquery.floatThead-slim.min.js

CDN Hosted

jQuery.floatThead is hosted on cdnjs.com, though sometimes it takes a bit for a new version to propagate there.


Install Using Bower

bower install floatThead

To report issues, visit the project's github issues page.
Or everything works great? Please  

License

Code is licensed under MIT, the docs under Creative Commons Attribution-ShareAlike 4.0 International
Copyright © 2012-2014 Misha Koryak (my last name at gmail)