Skip to content
A jQuery plugin that makes large tables more usable by having the table header stick to the top of the screen when scrolling.
Branch: master
Clone or download
Latest commit 8e02a39 Jan 14, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo Rename events and add example May 21, 2015
js 0.1.24 Jan 14, 2018
.gitignore
.npmignore Add .npmignore and rename module in package.json May 21, 2015
Gruntfile.js Never forget to bump bower.json again Jan 14, 2018
bower.json 0.1.24 Jan 14, 2018
composer.json
license.txt license info added Nov 4, 2011
package.json 0.1.24 Jan 14, 2018
readme.md

readme.md

StickyTableHeaders

So what's it good for? Well, let's say you want to display a long list of fairly uniform tabluar data, like stock exchange listings or sport statistics but you don't want your users to get lost in the data as they scroll down on the page.

StickyTableHeaders to the rescue: By applying the StickyTableHeaders jQuery plugin to the table, the column headers will stick to the top of the viewport as you scroll down.

Go ahead and try out a demo.

The code is based on this proof of concept.

Installation

The best way to install is using npm:

npm install sticky-table-headers

or Bower:

bower install StickyTableHeaders

or by loading it directly from the unpkg CDN:

<script src="https://unpkg.com/sticky-table-headers"></script>

Usage

Initializing the plugin is pretty straight forward:

$('table').stickyTableHeaders();

Tear down

To remove the plugin:

$('table').stickyTableHeaders('destroy');

Trigger an update manually

$(window).trigger('resize.stickyTableHeaders');

Options

You can initialize the plugin with an options map to tweak the behavior. The following options are supported:

fixedOffset

A number or jQuery object specifying how much the sticky header should be offset from the top of the page:

$('table').stickyTableHeaders({fixedOffset: $('#header')});

scrollableArea

A DOM element or jQuery object. Allows you to overwrite which surrounding element is scrolling. Defaults to window. Check this demo for an example:

$('table').stickyTableHeaders({scrollableArea: $('.scrollable-area')});

cacheHeaderHeight

Performance tweak: When set to true the plugin will only recalculate the height of the header cells when the width of the table changes.

Default value: false

$('table').stickyTableHeaders({cacheHeaderHeight: true});

z-index

The plugin uses z-index to make the thead overlay the body. You can override the z-index value by passing in a zIndex option:

$('table').stickyTableHeaders({zIndex: 999});

Reinitialize

As described in pull request #33 responsive pages might need to reinitialize the plugin when the user resizes his browser. This is can be done by calling the plugin with the new options:

$('table').stickyTableHeaders({fixedOffset: [new-offset]});

Events

The plugin triggers the following events on the targeted <table> element:

  • clonedHeader.stickyTableHeaders: When the header clone is created.
  • enabledStickiness.stickyTableHeaders: When the sticky header is enabled.
  • disabledStickiness.stickyTableHeaders: When the sticky header is disabled.

Confused?

If any of this is confusing, please check out the /demo folder. There are a couple of examples in there. E.g. you can see how to use it with Twitter Bootstrap.

Known Issues

  • Internet Explorer: You need to set the padding of the <th>s explicitly in the css in order to make the plugin work
  • Internet Explorer: Adding horizontal margin to the table causes the header to be misaligned when scrolling. (Issue #10)
  • Using the plugin together with tablesorter breaks in Internet Explorer 8

Browser Support

The plugin has been verified to work in:

  • Chrome 35
  • Firefox 29
  • Internet Explorer 8-11
  • Safari 5

NOTE: It does not work in Internet Explorer 7 (but it degrades nicely)

You can’t perform that action at this time.