What react-headroom is and when to use it

React Headroom is a lightweight React component that hides the header on scroll down and shows it on scroll up, delivering a compact, distraction-free reading experience. It’s ideal for top navigation bars, in-app toolbars, and sticky headers where screen real estate matters. The library handles scroll detection, state transitions, and edge cases like initial pin state and window resizes.

Use react-headroom when you need a predictable auto-hiding header without wiring complex scroll listeners yourself. It abstracts the scroll threshold, debouncing, and pin/unpin logic, so you can focus on animations, accessibility, and visual polish. If your project needs server-side rendering, be mindful of hydration (see the “Troubleshooting” section).

The component is small, works with functional and class components, and integrates easily with CSS-in-JS. For a practical walkthrough, check this practical react-headroom tutorial that walks through setup and usage examples.

Installation and basic setup

Install via npm or yarn. This adds the package to your dependencies so you can import Headroom into your React components. Use the commands below in your project root:

npm install react-headroom
# or
yarn add react-headroom

Once installed, import and wrap your header component. The simplest usage is one line: import Headroom and wrap your nav. This provides auto-hiding behavior with sensible defaults.

For a quick reference on installation and more environment-specific notes (e.g., Next.js, CRA), see the package page on npm: react-headroom installation. That resource lists versions and peer dependencies.

Example: minimal auto-hiding header

Here’s a minimal, copy-paste example using a functional component and react-headroom. It demonstrates a sticky nav that hides on scroll down and reveals on scroll up. Paste into any React app and tweak the styles to match your design system.

import React from 'react';
import Headroom from 'react-headroom';

function AppHeader() {
  return (
    <Headroom>
      <header style={{ background:'#fff', padding:'12px 24px', boxShadow:'0 1px 0 rgba(0,0,0,0.06)' }}>
        <nav>My App — Navigation Links</nav>
      </header>
    </Headroom>
  );
}

This example uses inline styles for brevity. In production, prefer CSS classes or CSS-in-JS so you can control transitions and reduce inline style overhead. The default Headroom behavior covers most layouts without extra props.

To test, scroll the page in your browser. The header will unmount visually by translating or toggling CSS depending on your configuration. If you need immediate control over animations, see the “Customization” section below.

Customization, animations, and props

react-headroom exposes props that let you tune when the header hides, how it animates, and whether inline styles are applied. Key props include disableInlineStyles, upTolerance, downTolerance, and calcHeightOnResize. Use disableInlineStyles to fully control transitions with your CSS.

Common approach: disable inline styles and add a CSS transition to your header class. This gives you consistent animations and keeps your CSS maintainable. For example, add a transform transition on the header element for smooth slide-up and slide-down effects.

Below is a compact list of the most useful props to tune behavior:

• disableInlineStyles — turn off built-in styles to use your CSS.
• upTolerance / downTolerance — pixels of tolerance before pin/unpin fires.
• pinStart — pixel offset before Headroom activates; set if you have hero content above nav.

Example: customizing with CSS transitions

/* styles.css */
.app-header {
  transition: transform 220ms ease-in-out;
}
.app-header--unpinned {
  transform: translateY(-100%);
}
.app-header--pinned {
  transform: translateY(0);
}

Apply these classes when you disable inline styles and let Headroom add/remove state classes via the `className` or follow the library’s state callbacks to toggle your own classes.

Scroll detection, callbacks, and integrations

Beyond visual hiding, you often need to detect header state changes for analytics, accessibility announcements, or to trigger other UI updates. react-headroom exposes lifecycle callbacks like onPin, onUnpin, and onUnfix to react to these events.

Use these callbacks to dispatch events (e.g., using a global state or analytics service), or to toggle other UI elements. For example, you might pause an autoplay carousel when the header unpins or send a “header hidden” event to your telemetry system.

Example usage with callbacks:

<Headroom
  onPin={() => console.log('header pinned')}
  onUnpin={() => console.log('header hidden')}
>
  <Header />
</Headroom>

For voice search and accessibility, keep the header content semantically correct: use <nav>, label landmarks, and avoid hiding interactive controls from assistive technologies. When you animate, ensure focus management remains predictable for keyboard users.

Troubleshooting, performance, and best practices

If the header jumps or flickers during initial load, check SSR hydration issues. When server-side rendering, ensure your header’s initial state matches the client. Setting `calcHeightOnResize` can help if dynamic content changes header height after mount.

Performance tips: avoid heavy work inside scroll listeners. Let react-headroom manage the scroll events and use callbacks sparingly. If you are adding additional scroll handlers, debounce or throttle them and avoid layout thrashing by reading layout values once per frame.

Common pitfalls and fixes:

• Header overlap with content — add top padding equal to header height or use CSS sticky placeholders.
• Animations not smooth — prefer GPU-friendly transforms (translateY) and avoid animating height.

Finally, test across devices: mobile scrolling velocity differs, and iOS overscroll can affect thresholds. Adjust downTolerance/upTolerance to get a consistent experience.

Where to learn more and sample projects

For deeper examples and a step-by-step getting started guide, the Dev.to walkthrough is practical and concise: Getting started with react-headroom — building auto-hiding navigation. It includes screenshots and a working demo that maps directly to the code samples above.

To inspect the package, changelog, and issues, visit the npm package page: react-headroom on npm. For source and contribution guidelines, check the repository linked from that page.

Use the examples above as a baseline. Start with defaults, then progressively disable inline styles and add your animations. That way you keep the behavior predictable while achieving a polished UI.

FAQ

How do I install react-headroom?

Install with npm or yarn: npm install react-headroom or yarn add react-headroom. Then import Headroom from ‘react-headroom’ and wrap your header component.

How do I create an auto-hiding header with React?

Wrap your header in <Headroom> from react-headroom. It auto-hides on scroll down and reveals on scroll up. Configure props like pinStart, upTolerance, and callbacks such as onPin to tune behavior.

How can I customize animations and detect scroll with react-headroom?

Disable inline styles via disableInlineStyles, then apply CSS transitions on classes. Use callbacks onPin/onUnpin to detect state changes and wire analytics or UI updates.

Useful links & backlinks

Official package and resources:

• react-headroom installation (npm)
• react-headroom tutorial — Dev.to guide

Credit: examples and practical workflow inspired by community guides and the official package documentation.