explaingit

wickynilliams/headroom.js

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

TLDR

Headroom.js is a tiny, dependency-free JavaScript library that hides your fixed website header when the user scrolls down and shows it again on scroll-up, freeing up screen space while reading.

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
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

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.

Tech stack

JavaScriptCSS

Getting it running

Difficulty · easy Time to first run · 5min
Free to use in any project, personal or commercial, with no restrictions.

In plain English

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?
Open on GitHub → Explain another repo

← wickynilliams on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.