jquery-sticky-table-header

jquery.stickyTableHeader

A small (2.4kb gzipped) and accessible jQuery plugin for adding sticky headers to large data tables.

Demo

https://simonsmith.github.io/jquery.stickyTableHeader/test/

Features

• Supports multiple tables on one page
• Uses position: fixed that allows smooth scrolling and a wide range of browser support
• Screenreader support
• Minimal DOM updates in scroll event

Installation

npm

It's recommended to require/import the plugin as part of an existing webpack or browserify setup:

npm install jquery jquery-sticky-table-header --save

// index.js
const $ = require('jquery');
require('jquery-sticky-table-header');
$('.table-container').stickyTableHeader();

Relies on jQuery as a peerDependency so ensure it is installed in your application.

Manual

1. Clone the repository
2. yarn && yarn run build or npm install && npm run build
3. A UMD version of the plugin will be available in the ./build directory.
4. Include it in your project as needed

Example

<script src="http://code.jquery.com/jquery-latest.js"></script>
<script src="jquery.stickyTableHeader.js"></script>

Usage

There are some HTML requirements for the plugin to function correctly:

• The table must be inside a containing element with no siblings
• There must be a thead element
• There must be a tbody element

Example

<div class="table-container">
  <table>
    <thead>
      <!-- content -->
    </thead>
    <tbody>
      <!-- content -->
    </tbody>
  </table>
</div>

$('.table-container').stickyTableHeader();

It's recommended that you apply a background colour to the header to mask the real table header beneath it.

Options

• outsideViewportOnly - (boolean) Only run the plugin if the table is larger than the viewport default true
• scrollThrottle - (number) Maximum number of times the scroll handler can be called over time in milliseconds default 50
• zIndex - (number) Added to the header to control stacking default 2
• offset (object) Offset values for the header
  • top (number) - Offset (in pixels) applied to the header default 0
  • topScrolling (string) - Offset (in pixels) applied to the header whilst scrolling default 0
• css (object) Classes applied to the HTML structure
  • header (string) - Added to the header that scrolls with the table default StickyTableHeader
  • scrolling (string) - Added to the header when it is scrolling with the viewport default is-scrolling
  • active (string) - Added to the original table when plugin is active default is-stickyTableHeaderActive

Methods

You can get at the instance by accessing it from the elements .data method

$('.table-container').stickyTableHeader();
const instance = $('.table-container').data('stickyTableHeader');
instance.destroy();

destroy

Removes the sticky header element and scroll listener

Development

yarn is required or you can use npm to run the individual scripts yourself

1. Clone the repository
2. yarn
3. yarn start

Run the tests with yarn test and view the demo at http://localhost:3002/test