Fork me on GitHub
Hey! This ad ⟶

Helps me pay for coffee!

Intro

jquery.floatThead is a floating/locked/sticky/fixed 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 and 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
  • Screen reader support
  • Bootstrap3 support

Requirements:

  • jQuery 1.8 or better (code is 1.9+ compliant)
    or jQuery 1.7 with jQuery UI 1.8.x
  • Internet Exploder 8+, 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 3 ways you can initialize the plugin:

  • 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
  • Responsive scrolling
    Hybrid of above. At some screen sizes horizontal scrolling happens within a container, vertical scrolling within the window

Window scrolling

is the default. Initialize floatThead without any params to use it.

var $table = $('table.demo');
$table.floatThead();

Overflow scrolling

You must specify a container element inside of which the table will scroll. This element must already exist in the DOM and wrap the table

var $table = $('table.demo');
$table.floatThead({
    scrollContainer: function($table){
        return $table.closest('.wrapper');
    }
});

Responsive window scrolling

You must specify a responsive container element within which the table will scroll horizontally at some screen sizes. A good example of this type of a container is bootstrap3's responsive-table helper.

var $table = $('table.demo');
$table.floatThead({
    responsiveContainer: function($table){
        return $table.closest('.table-responsive');
    }
});

This plugin supports perfect-scrollbar, if you want fancy stylable scrollbars.

Options

Note: All the options which are functions take a single argument: $table - the table on which floatThead was initialized.
ex: function($table){ ... }
Name type default description
position string 'auto' Valid values: 'auto', 'fixed', 'absolute'.
Position the floated header using absolute or fixed positioning mode (auto picks best for your table scrolling type). Try switching modes if you encounter layout problems.
scrollContainer function or true null Defines a container element inside of which the table scrolls vertically and/or horizontally. If boolean true is used, then we use the table's offsetParent.
responsiveContainer function null Defines a responsive container element inside of which the table scrolls horizontally (at some resolutions), everything else behaves like window scrolling. This option cannot be used together with scrollContainer option. bootstrap3 example
headerCellSelector string tr:first>th:visible Specifies the selector used to find header cells (in the table's thead element)
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
top number or function 0 Offset from the top of the window where the floating header will 'stick' when scrolling down
bottom number or function 0 Offset from the bottom of the window where the floating header will 'stick' when scrolling down
zIndex number 1001 z-index of the floating header
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.
autoReflow boolean false

Experimental

use MutationObserver (on good browsers) to reflow automatically when internal table DOM changes, or DOM within scrollContainer

Methods

.floatThead('destroy')

Removes the widget from the table, returns a function to reinit the plugin with original options

var $table = $('table.demo1');
// float the headers
$table.floatThead({top: 25});
// unfloat the headers
var reinit = $table.floatThead('destroy');
// ... later you want to re-float the headers with same options
reinit();


.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 Consumed

reflow

$table.trigger('reflow')

Trigger this on a table (post plugin init) to force the plugin to re-align the floated header. You will need to do this if you enbiggen or ensmallen any column widths via DOM modifications, add/remove columns or change the table's location in the DOM while using the position:'fixed' option.
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');

Events Produced

floatThead

$table.on('floatThead', function(e, isFloated, $floatContainer){..}

The plugin will trigger this event on the table when the header is floated and unfloated. The 2nd and 3rd params in the method are of interest to you. As shown below, be certain to add your event handlers before calling `.floatThead()`, or your code may miss `floatThead` events.
var $table = $('table.demo2');
$table.on("floatThead", function(e, isFloated, $floatContainer){
    if(isFloated){
        $floatContainer.addClass("floated"); // the div containing the table containing the thead
        $(this).addClass("floated"); // $table
    } else {
        $floatContainer.removeClass("floated");
        $(this).removeClass("floated");
    }
});
$table.floatThead(...);
table.floated {
  background-color: #d5ffd5;
}

reflowed

$table.on('reflowed', function(e, $floatContainer){..}

The plugin will trigger this event on the table after every reflow. It can be useful to know when the plugin is done with its header re-layout.

At least one reflow is guaranteed on init, but others will follow. Note that these conditions may generate multiple reflow events. It may be wise to debounce the event handler.

Reflow will happen on:

  • Plugin init
  • $(window).on('load') (for tables with images)
  • $(window).on('resize')
  • Sort, filter or paginate within a datatable
  • Manually trigger the reflow event or call the reflow method on the table
  • Switch to a bootstrap 3 or jQueryUI tab containing $table
  • With autoReflow option enabled, modify the table DOM



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().remove();
	//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({
	position: 'fixed'
});

Open Issues

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


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

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 beer!



Or... why program when you can look at cat pictures?! Probably because you can't earn a living doing that? Or can you?
You decide.



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

Unstable pre-release code

Are you a hipster who likes running code with unreleased features and bugs?

I know I do, because that is the code that runs on this doc site.

Head right over to the /dist directory on the master branch and enjoy.


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

Install Using NPM

npm install floatthead


Need 1.2.x docs? here are the 1.2.13 docs

License

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