Skip to content
Get packs

Headroom.js

A small dependency-free script that hides your page header while scrolling down and shows it when scrolling up

GitHub Download v0.11.0
Stars
10.8k
Forks
796
Licence
MIT
Language
JavaScript
Last update
3.0 years ago
Type
Library

No commits in over a year — check for forks or alternatives before adopting.

What it is

Headroom.js is a lightweight JavaScript widget with no dependencies that reacts to the user's scroll. It adds CSS classes to an element, such as a site header, so it slides out of view when the user scrolls down and slides back in when they scroll up. Website builders use it to keep navigation out of the way while still letting it return quickly.

  • Hide a site header while the user reads down a long article and bring it back on scroll up
  • Attach the widget to any element you choose, not only a header, by passing it to the constructor
  • Style the pinned and unpinned states with your own CSS classes

Great for

  • Website developers who want a sticky header that hides on scroll down
  • Front-end developers who prefer a small script with no dependencies
  • Sites that load the script via a script tag, CommonJS, or AMD using the universal build

Not ideal for

  • Developers who need a full animation library, since this only toggles CSS classes for a header-style effect
  • Projects that cannot add a CSS transition to their header, because the README's example depends on CSS styling to produce the motion
Step-by-step guide: how to use Headroom.jsInstall, first run, examples, tips and FAQs

How to get it

  1. 1

    Install with a package manager

    Install with npm

    npm install headroom.js --save

    Or install with yarn

    yarn add headroom.js
  2. 2

    Run it

    • Install the package with npm or yarn, or load the unpkg build with a script tag
    • Select your header element with document.querySelector("header")
    • Create an instance with new Headroom(header) and call headroom.init()
    • Add the README's CSS for .headroom, .headroom--pinned, and .headroom--unpinned to your page
    • Scroll the page to see the header slide in and out
  3. 3

    Get the most out of it

    • Use the universal build from unpkg if you are not using a bundler
    • Change the transition timing in the .headroom class to adjust the speed of the slide
    • Read the full documentation on the project website for configuration options
    • Apply the widget to other elements, not only headers, as the quick start selects an element of your choice

Downloads

Source code (.zip)master branch · straight from GitHubRelease v0.11.0Release notes and sourceOfficial website & docswicky.nillia.ms/headroom.js/

Strengths

  • No dependencies, according to the README
  • Available on npm and through a universal build on unpkg
  • Includes a short quick start with example JavaScript and CSS

Trade-offs

  • The README is short; full options and API details are only on the external documentation website
  • Last code push in the metadata is October 2023, so check whether it still fits your needs
  • The visual effect depends on CSS you add yourself

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.