TIP: Try navigating through list using left & right arrow keys


Give your pages some headroom. Hide your header until you need it

Github issues
Github stars
1 day ago
Github last update date
NPM current week downloads


Headroom.js is a lightweight, high-performance JS widget (with no dependencies) that allows you to react to the user's scroll. The header on this site is a living example, it slides out of view when scrolling down and slides back in when scrolling up.


Headroom.js is available on npm. To install:

npm install headroom.js --save

# or...
yarn add headroom.js

A a universal build (suitable for script tags, CommonJS, and AMD) is available from unpkg.com:



For complete documentation please visit the headroom.js website.

Quick start

After installing headroom.js. The following JS will create and initialise a headroom instance:

import Headroom from "headroom.js";

// select your header or whatever element you wish
const header = document.querySelector("header");

const headroom = new Headroom(header);

Then you can add the following CSS to your page:

.headroom {
  will-change: transform;
  transition: transform 200ms linear;
.headroom--pinned {
  transform: translateY(0%);
.headroom--unpinned {
  transform: translateY(-100%);

You should now see your header slide in and out in response to the user's scroll.

Contributions & Issues

Contributions are welcome. Please clearly explain the purpose of the PR and follow the current code style.

Issues can be resolved quickest if they are descriptive and include both a reduced test case and a set of steps to reproduce.

Contributing Guide


The following steps will get you setup to contribute changes to this repo:

  1. Fork the repo (click the Fork button at the top right of this page)
  2. Clone your fork locally
git clone https://github.com/<your_github_username>/headroom.js.git
cd headroom.js
  1. Install dependencies. This repo uses npm, so you should too.
npm install


To build the project:

npm run build

To start a watcher for building the project and running tests:

npm start


To run the test suite in headless mode:

npm test


Licensed under the MIT License.

Buy us a coffeeBuy us a coffee