What is headroom.js?

wickynilliams/headroom.js — explained in plain English

Analysis updated 2026-06-24

★ 10,830JavaScriptAudience · developerComplexity · 2/5LicenseSetup · easy

Mindmap

mindmap
  root((repo))
    What It Does
      Hide header on scroll down
      Show header on scroll up
      More reading space
    Setup
      npm or yarn
      Script tag CDN
      CSS animation rules
    Features
      No dependencies
      Configurable offset
      CSS class toggling
    Audience
      Web developers
      Frontend designers

mindmap root((repo)) What It Does Hide header on scroll down Show header on scroll up More reading space Setup npm or yarn Script tag CDN CSS animation rules Features No dependencies Configurable offset CSS class toggling Audience Web developers Frontend designers

Click or tap to explore — scroll the page freely

What do people build with it?

USE CASE 1

Add a scroll-aware header to any website that disappears while reading and reappears when the user scrolls back up.

USE CASE 2

Improve mobile reading experience by reclaiming vertical screen space taken by a fixed navigation bar.

USE CASE 3

Customize the show/hide animation style and timing using your own CSS rules on the classes Headroom toggles.

What is it built with?

JavaScriptCSS

How does it compare?

	wickynilliams/headroom.js	mathjax/mathjax	withspectrum/spectrum
Stars	10,830	10,824	10,837
Language	JavaScript	JavaScript	JavaScript
Setup difficulty	easy	easy	hard
Complexity	2/5	2/5	4/5
Audience	developer	developer	developer

Figures from each repo's GitHub metadata at analysis time.

How do you get it running?

Difficulty · easy Time to first run · 5min

Free to use in any project, personal or commercial, with no restrictions.

So what is it?

Headroom.js is a small JavaScript library that watches a page's scroll position and shows or hides a fixed header based on which direction the user is scrolling. When you scroll down, the header slides out of view to give more reading space. When you scroll back up, the header reappears. The idea is that a header is most useful when you are moving back toward the top of a page, so hiding it while moving down keeps the content area clear. The library has no external dependencies, meaning you do not need jQuery or any other library installed alongside it. You add it to a project via npm or yarn, or by linking to a hosted file directly. Setup takes just a few lines of JavaScript: you point the library at your header element, call an init method, and add a handful of CSS rules that control the slide animation. The CSS classes the library toggles are standard, so you can adjust the animation timing or style however you like. All configuration and detailed documentation are on the project's own website rather than in the README. The README itself is brief and covers installation, a quick start example, and instructions for contributors who want to build or test the project locally. The library is released under the MIT license, which allows free use in personal and commercial projects.

Copy-paste prompts

Prompt 1

Add headroom.js to my existing site so the sticky nav bar hides when I scroll down and reappears when I scroll up. Show me the JavaScript init code and the minimum CSS I need.

Prompt 2

I'm using headroom.js but the header flickers on fast scrolls. How do I tune the tolerance and offset options to smooth it out?

Prompt 3

How do I use headroom.js without npm, just a script tag, on a plain HTML page with a fixed header div?

Frequently asked questions