Guide · Open source

How to use headroom.js: hide a header on scroll down

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Headroom.js is a lightweight JavaScript widget with no dependencies that reacts to the user's scroll. It is aimed at website developers and front-end developers who want a header that slides out of view when the user scrolls down and returns when they scroll up. This guide shows how to install it, initialise it on an element and add the CSS that produces the motion.

Headroom.jsWickyNilliams/headroom.js · ★ 10.8k · MIT Install options & downloads

Quick start

1Install the package. Run npm install headroom.js --save or yarn add headroom.js in your project.
2Import Headroom. Import Headroom from headroom.js in your script.
3Select an element. Use document.querySelector to pick the header or other element to control.
4Create and initialise. Call new Headroom(element) and then headroom.init().
5Add the CSS. Add the .headroom, .headroom--pinned and .headroom--unpinned rules so the element transitions with transform.
6Test the scroll. Scroll down to confirm the header slides out and scroll up to confirm it slides back in.

What headroom.js does

Headroom.js adds CSS classes to an element, such as a site header, based on the user's scroll direction. Your own CSS turns those class changes into movement. The README's example slides the header out of view when scrolling down and back in when scrolling up.

It only toggles classes, so it is a small tool for a header-style effect rather than a full animation library.

Install headroom.js with npm or yarn

Headroom.js is available on npm. Run one of the following commands in your project folder. The README lists no prerequisites.

If you do not use a package manager, the README says a universal build suitable for script tags, CommonJS and AMD is available from unpkg.com at https://unpkg.com/headroom.js.

npm install headroom.js --save

# or...
yarn add headroom.js

Create and initialise a Headroom instance

Import Headroom, select the element you want to control and create an instance. Then call init(). The README's example uses a header element, but any element you choose will work.

import Headroom from "headroom.js";

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

const headroom = new Headroom(header);
headroom.init();

Add the CSS that makes the header slide

Headroom.js needs CSS to produce the motion. The README's styles add a transition to the .headroom class, then move the element with translateY depending on whether it is pinned or unpinned.

Without this CSS, the classes change but the header will not visibly slide.

headroom: sets will-change and a 200ms linear transform transition
headroom--pinned: translateY(0%), the header is shown
headroom--unpinned: translateY(-100%), the header slides out of view

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

Check that it works

After adding the script and CSS, scroll your page. The README says you should see your header slide in and out in response to the user's scroll.

For full options and more detail, the README points to the documentation on the headroom.js website at http://wicky.nillia.ms/headroom.js.

Contribute or report an issue

The README welcomes contributions and asks that PRs clearly explain their purpose and follow the current code style. Issues are resolved fastest when they are descriptive and include a reduced test case and steps to reproduce.

To work on the repo, fork it, clone your fork, and run npm install. Then use npm run build to build, npm start for a build watcher and tests, and npm test to run the test suite in headless mode.

git clone https://github.com/<your_github_username>/headroom.js.git
cd headroom.js
npm install

What people use it for

Keeping site navigation out of the way while reading long pages, with the header returning when the user scrolls up.
Adding a sticky header that hides on scroll down for a website built with a front-end framework or plain JavaScript.
Loading a small script with no dependencies via a script tag, CommonJS or AMD using the universal build.

Frequently asked questions

Is headroom.js free to use?

Yes. Headroom.js is licensed under the MIT License, as stated in the README. Check the license file in the repository for the full terms.

What are the requirements for headroom.js?

The README lists no prerequisites. You install it with npm or yarn, or load the universal build from unpkg.com with a script tag, CommonJS or AMD.

How do I install headroom.js?

Run npm install headroom.js --save or yarn add headroom.js. If you do not use a package manager, the README points to the universal build at https://unpkg.com/headroom.js.

Why doesn't my header slide when I scroll?

Headroom.js only adds classes. The motion comes from your CSS, so make sure the .headroom, .headroom--pinned and .headroom--unpinned rules from the README are on the page.

Can I use headroom.js for animations other than a header?

The README describes it as a widget that reacts to scroll for a header-style effect. It is not described as a full animation library, so projects needing broad animation features may need another tool.

Does headroom.js have alternatives?

The source does not list comparable projects, so this guide cannot compare it with specific alternatives. The README's documentation at http://wicky.nillia.ms/headroom.js is the place to check its options.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Headroom.js suits developers who want a small, dependency-free script that hides a header on scroll down and shows it on scroll up, and who are comfortable writing a CSS transition. If you need a full animation library or cannot add CSS to your header, pick a different tool.

Install options & downloads