This plugin is an Alpine.js directive called x-headroom, designed to implement a smart sticky header behavior (commonly known as "headroom" logic) on any DOM element—typically navigation bars or headers. It dynamically adds and removes CSS classes based on the user's scroll position, enabling smooth animations and responsive UI changes such as hiding the header when scrolling down and showing it when scrolling up.
The plugin is inspired by the popular Headroom.js library but implemented as a lightweight, native solution using Alpine.js, with first-class support for Tailwind CSS via flexible class handling.
- Easy setup with Alpine.js directive
- Customizable options for offset, tolerance, classes
- Supports Tailwind CSS classes
- Performance optimized with requestAnimationFrame, passive event listeners
- Optional
frozenmodifier for static state
Install via npm or bun in your JavaScript project root directory:
npm install @designbycode/alpine-headroom
# or
bun add @designbycode/alpine-headroomEnsure you use Tailwind CSS v4 only in your build config
Import and register the plugin in your entry point (eg main.js):
import Alpine from "alpinejs"
import Headroom from "@designbycode/alpine-headroom"
Alpine.plugin(Headroom)
Alpine.start()Add the x-headroom directive to any element:
<header x-data x-headroom="{ offset: 50, tolerance: 10, classes: { pinned: 'bg-white shadow', unpinned: 'opacity-75', frozen: 'bg-gray-500' } }">
<!-- header content -->
</header>offset(number) minimum scroll Y before toggling pinned/unpinnedtolerance(number) scroll delta threshold to ignore small movesclasses(object) override default Tailwind CSS v4 class names
.headroom {
will-change: transform; /* Optimize for animation */
transition: transform 0.5s ease-in-out; /* Smooth transition */
position: fixed;
top: 0;
left: 0;
right: 0;
z-index: 1000;
}
/* Styles when the element is pinned (visible) */
.headroom--pinned {
transform: translateY(0%);
}
/* Styles when the element is unpinned (hidden) */
.headroom--unpinned {
transform: translateY(-100%); /* Slide up and out of view */
}
/* Optional: Styles for when the page is at the very top */
.headroom--top {
/* Example: Add a shadow only when not at the top */
box-shadow: none;
}
.headroom--not-top {
box-shadow: 0 3px rgba(0,0,0,25);
}Use modifiers in the directive to apply frozen state at init:
<nav x-data x-headroom.frozen="">
<!-- nav content -->
</nav>Default options are:
{
offset: 0,
tolerance: 0,
classes: {
initial: "headroom",
pinned: "headroom--pinned",
unpinned: "headroom--unpinned",
top: "headroom--top",
notTop: "headroom--not-top",
bottom: "headroom--bottom",
notBottom: "headroom--not-bottom",
frozen: "headroom--frozen"
}
}Override any of these by passing an object to x-headroom="..." expression, customising only what you need, classes supports multiple Tailwind utility classes separated by spaces
// headroom.ts
import Alpine from "alpinejs"
import Headroom from "@designbycode/alpine-headroom"
Alpine.plugin(Headroom)
Alpine.start()<!-- index.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Alpine Headroom Demo</title>
<link href="/dist/output.css" rel="stylesheet">
</head>
<body>
<header x-data x-headroom.x="{ offset: 100, tolerance: 20 }" class="fixed top-0 w-full p-4 transition-all duration-300">
<h1 class="text-xl font-bold">My Site</h1>
</header>
<main class="mt-20 p-4">
<p>Scroll down to see header hide, scroll up to show</p>
<!-- more content -->
</main>
<script src="/dist/main.js"></script>
</body>
</html>- fork the repo
- install dependencies
- make your changes
- open a pull request