React Headroom: Auto-Hiding Header — Tutorial, Setup & Examples
Short description: Practical guide to using react-headroom for auto-hiding sticky navigation. Install, implement, customize animations, and optimize for performance with copy-paste-ready code.
Quick answer (for featured snippets & voice search)
React Headroom is a small React component that hides the header while scrolling down and reveals it when scrolling up. Install with npm install react-headroom or yarn add react-headroom, wrap your navigation in the <Headroom> component, and configure props such as upTolerance, downTolerance, and pinStart to control when the header hides or shows.
This behavior improves viewport space on mobile and keeps navigation accessible. Use CSS transitions or inline styles to add slide/fade animations and tune thresholds for a smooth UX.
For a step-by-step tutorial and more examples, see this react-headroom tutorial: Getting started with react-headroom — building auto-hiding navigation.
Why use react-headroom?
React Headroom provides a single-purpose, predictable pattern for auto-hiding headers. It saves vertical real estate on scroll-heavy pages — particularly valuable on mobile where screen height is limited. Unlike a custom onscroll handler, react-headroom abstracts debouncing, thresholds, and lifecycle concerns into a well-tested component, reducing boilerplate and bugs.
The library is lightweight and integrates seamlessly with functional components, hooks, and styling solutions. It supports common controls like tolerances (how sensitive it is to scroll), pin start (when to begin hiding/pinning), and a simple CSS-driven animation model, letting you focus on UX instead of the mechanics of scroll detection.
Common use cases include documentation headers, e-commerce filters, blog/top navigation, and any app where you want navigation accessible but not always intrusive. It plays nicely with sticky positioning and can coexist with other scroll-aware libraries when configured correctly.
Installation and setup
To get started, install the package with your package manager. Use npm:
npm install react-headroom --saveor yarn:
yarn add react-headroomThen import and wrap your header component in <Headroom>. Below is a minimal setup for a functional React app. This example shows the most common props you’ll want to tune: style, upTolerance, and downTolerance.
import React from 'react'
import Headroom from 'react-headroom'
export default function AppHeader() {
return (
<Headroom upTolerance={10} downTolerance={10} pinStart={50}>
<header className="site-header">
<nav>/* logo + links */</nav>
</header>
</Headroom>
)
}Place the wrapped header near the top of your app layout so it remains mounted across route changes if you want consistent behavior. If using server-side rendering, ensure your initial CSS matches the headroom classes to avoid a flash of misplaced header.
Basic example: Auto-hiding header in practice
The default Headroom behavior is: visible by default, hide when scrolling down, reveal when scrolling up. A practical pattern is to combine it with a transparent-to-solid background transition: transparent at top of page, solid color once scrolled. This improves legibility while preserving an immersive top area.
Here’s a ready-to-use example that adds a CSS transition and a shadow when pinned. The CSS transition makes the reveal feel natural and reduces jank on lower-end devices.
/* CSS */
.site-header{position:fixed;top:0;left:0;right:0;transition:transform .25s ease,background .25s ease}
.site-header.headroom--unpinned{transform:translateY(-100%)}
.site-header.headroom--pinned{transform:translateY(0);box-shadow:0 2px 6px rgba(0,0,0,0.12)}
.site-header--scrolled{background:rgba(255,255,255,0.98)}Combine the above CSS with Headroom props like disableInlineStyles (to rely on your CSS classes) and pinStart to control when the header becomes “sticky” or pinned. Tweak tolerances to match your desired sensitivity: smaller values react faster, larger values reduce accidental triggers.
Customization, animations, and scroll detection
react-headroom offers flexible customization: you can enable or disable inline styles, supply custom class names, and use lifecycle callbacks. For animation, prefer CSS transforms (translateY) over top/height changes to leverage GPU acceleration and avoid layout thrashing. A short easing curve (0.2–0.3s) feels responsive without being snappy.
Key props to customize behavior:
upTolerance,downTolerance— sensitivity to vertical deltapinStart— pixel offset where Headroom activatesdisableInlineStyles— use your own CSS classes
For scroll detection beyond basic show/hide, integrate react-headroom state with hooks or context. Example: expose whether the header is pinned and change content (compact menu, search icon) based on that state. Listen to window.scroll or use IntersectionObserver for more complex triggers like section-aware nav highlighting.
Best practices and performance tips
Keep the header lightweight. Avoid heavy DOM and expensive renders inside the header; expensive child updates can cause jank during reveal/hide. Memoize header children and avoid inline functions that cause re-renders on each frame. Use requestAnimationFrame for any bespoke scroll listeners you add.
Prefer CSS transforms and opacity transitions to minimize layout recalculations. If you need to animate height or complex properties, throttle updates and consider layering animations to keep the main thread responsive. Test on low-end devices and mobile to validate the feel — what’s smooth on desktop may stutter on older phones.
When combining react-headroom with other libraries (e.g., virtualized lists or heavy analytics), isolate the header’s render tree and avoid passing large prop objects that change frequently. This reduces unnecessary reconciliations and keeps the header’s animation smooth.
Example: Advanced setup with React Router and hooks
In single-page apps, keep the header mounted across route changes so it maintains scroll-aware behavior. If you unmount the header on navigation you lose the scroll state. Use layout-level components to ensure a consistent header instance across routes.
import Headroom from 'react-headroom'
import {useLocation} from 'react-router-dom'
function HeaderWrapper(){
const {pathname} = useLocation()
// Example: hide header on specific pages
const hiddenOn = ['/login','/checkout']
if(hiddenOn.includes(pathname)) return null
return (
<Headroom disableInlineStyles>
<Header />
</Headroom>
)
}Use the router location to conditionally render header variants (compact vs full) and pass analytics only when appropriate. Keep Headroom props stable to avoid reinitialization when route changes occur.
Integrations and accessibility
Ensure keyboard navigation remains functional when the header hides. Don’t remove focusable elements from the DOM; instead, move them off-screen or maintain visibility for keyboard users. Use ARIA landmarks (<nav aria-label="Main navigation">) and test with screen readers to verify the header reveal doesn’t confuse assistive tech.
For mobile, confirm tappable targets remain reachable after the reveal animation. Consider a short delay before the header hides if a user interacts near the top to avoid interrupting intentional taps. Always test with real devices and accessibility tools.
When linking to pages, preserve expected anchor behavior: if a link jumps to a section near the top, the pinned header may overlap content. Use CSS scroll-padding-top or calculate offsets to avoid hidden anchors.
FAQ
What is react-headroom and how does it work?
React Headroom is a small, focused library that hides the header when scrolling down and reveals it when scrolling up. It listens to scroll events, calculates direction and deltas, and toggles classes (unpinned/pinned) so you can animate the header with CSS.
How do I install and set up react-headroom in a React project?
Install with npm install react-headroom or yarn add react-headroom. Import Headroom and wrap your header component. Customize using props like upTolerance, downTolerance, and pinStart, and use CSS transforms for smooth animations.
How can I customize animations and avoid janky behavior?
Use CSS transforms (translateY) and opacity with GPU-accelerated properties. Avoid animating height/top. Keep header children light and memoized. Tune tolerances and pinStart for a natural feel and test on low-end devices to validate performance.
Semantic core (expanded keywords & clusters)
Below is the grouped semantic core — primary queries, secondary variants, and clarifying LSI terms to use across content, meta, and anchor texts. Use these phrases naturally in headings, alt text, and link anchors.
Primary keywords: - react-headroom - React auto-hiding header - react-headroom tutorial - React sticky navigation - react-headroom installation - React hide on scroll - react-headroom example - react-headroom setup - React navigation header Secondary / high-intent variants: - react-headroom getting started - React scroll header - react-headroom customization - react-headroom animations - react-headroom setup guide - react-headroom npm install - react-headroom usage example - react-headroom props upTolerance downTolerance Clarifying / LSI / long-tail: - auto hide header react on scroll - sticky navigation react library - tutorial react sticky header hide on scroll - react header hide and show on scroll example - how to customize react-headroom animations - disableInlineStyles react-headroom example - react-headroom with react-router - accessibility auto hide header - performance tips react-headroom Voice-search / question style phrases: - "How do I install react-headroom?" - "What is react-headroom used for?" - "How to hide header on scroll in React?"
Backlinks and references
For a guided walkthrough and extra examples, follow this in-depth react-headroom tutorial. The tutorial includes a sample project and step-by-step screenshots to speed up implementation.
Micro-markup suggestion (JSON-LD)
Add this JSON-LD to the page head or body to enable rich results for the FAQ and Article.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "React Headroom: Auto-Hiding Header — Tutorial, Setup & Examples",
"description": "Learn how to install, set up, and customize react-headroom for auto-hiding sticky navigation. Examples, animation tips, and ready-to-use code.",
"mainEntity": [
{
"@type": "Question",
"name": "What is react-headroom and how does it work?",
"acceptedAnswer": {
"@type": "Answer",
"text": "React Headroom hides the header on scroll down and reveals it on scroll up. It toggles classes so you can animate via CSS."
}
},
{
"@type": "Question",
"name": "How do I install and set up react-headroom?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Install with npm or yarn, import Headroom and wrap your header. Configure upTolerance, downTolerance, and pinStart as needed."
}
},
{
"@type": "Question",
"name": "How can I customize animations and avoid janky behavior?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Use CSS transforms and opacity, keep header children lightweight, memoize components, and test on low-end devices."
}
}
]
}That’s it — this article is ready to publish. If you want, I can also generate a compressed CSS snippet, a sandbox-ready CodeSandbox link, or a copy optimized for AMP pages.