Fork me on GitHub

Demo Pages Moved!!!

If you are reading this, it means that my magical meta-refresh tag did effect you! This is the old version of the plugin/docs. The new version is here:

http://mkoryak.github.io/floatThead/

Intro

I was fed up the current state of floating header plugins. They either lose your styles or lose your events, or dont support the edge cases.
This is why i wrote jQuery.floatThead.

Features:

  • Floats the table header - so that the user can always see it
  • Supports tables with inner scroll bars, or whole page scrolling
  • Horizonal or vertical scrolling
  • Doesnt clone the thead - so your events stay bound
  • Doesnt 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 or jQuery 1.7.x + jQuery UI core
  • Underscore.js 1.3 or better
  • IE8, IE9, FF10+ or Chrome15+

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:

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

Internal 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 contaier 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
getSizingRow function null The plugin uses the first row in the table body to calculate floated header's column sizes. It expects this row to contain <td>s with colspan of at most 1. If the first row does not meet that requirement, you must implement this function.

Returns: jquery object containing tds. Length of this element much match the number of columns in the table.
example use
useAbsolutePositioning boolean true Position the floated header using absolute positioning or using fixed positioning. Fixed positioning peforms 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
cellTag string th Specifies which tag is used in the header to specify cells
example use

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');

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

Internal Scrolling

Internal scrolling is used when the table is inside of a container smaller than itself.
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.

Code
var $demo1 = $('table.demo1');
$demo1.floatThead({
	scrollingTop: 41,
	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

Page Scrolling

Page scrolling isused when you have a large table that takes up the whole screen.
Code
$('table.demo2').floatThead({
	scrollingTop: 41,
	// I need this offset because i dont 
	// want the table header to overlap 
	//my site navigation
	useAbsolutePositioning: false 
	// absolutePositioning is better for 
	//highly dynamic sites 
	//(which this is not)
});

Known Issues

Issues list is pulled from github

  • There are no issues! Yey!


Download

This plugin is in beta.
You can grab the latest non-minified version at github
and a minified version here (4.6K Minified version can lag behind latest version!!)
To report issues, visit the project's github repository page.

NOTE: The code included on this page is used for developing new features and fixing bugs. Use the code in github.

TODO:

  • fix spellign!
  • stablize code
  • cleanup code