@designbycode/alpine-headroom
v1.0.7
Published
A lightweight Alpine.js directive that toggles CSS classes based on scroll position, it handles pinned, unpinned, top, bottom, frozen states with custom options for offset and tolerance
Maintainers
designbycode_Readme
Alpine Headroom Plugin
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.
Features
- 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
Installation
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
Usage
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()HTML Markup
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>Options
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
Code Example
// 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>Contributing
- fork the repo
- install dependencies
- make your changes
- open a pull request