Что такое Headroom.js

Headroom.js — это лёгкая JavaScript-библиотека, предназначенная для управления видимостью элементов интерфейса в зависимости от прокрутки страницы. Чаще всего используется для создания «умных» шапок (header), которые скрываются при прокрутке вниз и появляются при прокрутке вверх.

Ключевая задача — улучшение пользовательского опыта за счёт экономии пространства на экране и обеспечения быстрого доступа к навигации.

Принцип работы

Библиотека отслеживает направление прокрутки страницы и изменяет CSS-классы элемента, к которому она применена.

Поведение можно описать следующим образом:

  • Прокрутка вниз → элемент скрывается
  • Прокрутка вверх → элемент появляется
  • При достижении верхней части страницы → элемент фиксируется в исходном состоянии

Headroom.js не занимается анимацией напрямую — она лишь добавляет и удаляет CSS-классы. Вся визуальная часть реализуется через CSS.

Подключение библиотеки

Существует два основных способа подключения:

Через CDN

<script src="https://unpkg.com/headroom.js@0.12.0/dist/headroom.min.js"></script>

Через пакетный менеджер

npm install headroom.js

Импорт в модульной среде:

import Headroom from "headroom.js";

Базовое использование

Инициализация происходит через создание экземпляра класса Headroom:

const header = document.querySelector("header");
const headroom = new Headroom(header);

headroom.init();

После этого библиотека начинает отслеживать прокрутку и применять соответствующие классы.

CSS-классы и их роль

Headroom.js добавляет и удаляет набор классов, определяющих состояние элемента:

  • headroom — базовый класс
  • headroom--pinned — элемент виден (закреплён)
  • headroom--unpinned — элемент скрыт
  • headroom--top — страница в верхней позиции
  • headroom--not-top — страница прокручена вниз
  • headroom--bottom — достигнут низ страницы
  • headroom--not-bottom — не достигнут низ страницы

Пример CSS для анимации:

header {
  transition: transform 0.3s ease;
}

.headroom--pinned {
  transform: translateY(0%);
}

.headroom--unpinned {
  transform: translateY(-100%);
}

Логика состояний

Состояния формируются на основе нескольких факторов:

Направление прокрутки

  • Вниз → unpinned
  • Вверх → pinned

Положение на странице

  • Вверху → top
  • Внизу → bottom

Порог чувствительности

Изменения состояния происходят не мгновенно, а после достижения определённого порога прокрутки (tolerance).

Настройки (Options)

Headroom.js предоставляет гибкую систему конфигурации.

Пример инициализации с параметрами:

const headroom = new Headroom(header, {
  offset: 100,
  tolerance: {
    up: 10,
    down: 5
  },
  classes: {
    initial: "headroom",
    pinned: "headroom--pinned",
    unpinned: "headroom--unpinned",
    top: "headroom--top",
    notTop: "headroom--not-top",
    bottom: "headroom--bottom",
    notBottom: "headroom--not-bottom"
  }
});

Основные параметры

offset

Определяет расстояние (в пикселях), после которого начинается реакция на прокрутку.

offset: 100

До достижения этого значения элемент остаётся в состоянии top.

tolerance

Задаёт чувствительность к прокрутке.

tolerance: {
  up: 10,
  down: 5
}
  • up — минимальное расстояние прокрутки вверх для изменения состояния
  • down — аналогично для прокрутки вниз

Позволяет избежать частых переключений при мелких движениях.

classes

Позволяет переопределить имена CSS-классов.

Полезно при интеграции в существующие проекты с собственной системой именования.

События (Callbacks)

Headroom.js поддерживает набор колбэков, вызываемых при изменении состояния.

Пример:

const headroom = new Headroom(header, {
  onPin: function() {
    console.log("Появился");
  },
  onUnpin: function() {
    console.log("Скрылся");
  },
  onTop: function() {
    console.log("Верх страницы");
  },
  onNotTop: function() {
    console.log("Не верх страницы");
  }
});

Доступные события

  • onPin — элемент стал видимым
  • onUnpin — элемент скрыт
  • onTop — достигнут верх страницы
  • onNotTop — пользователь прокрутил вниз
  • onBottom — достигнут низ страницы
  • onNotBottom — пользователь ушёл от нижней границы

Управление состоянием вручную

Headroom.js предоставляет методы для ручного управления:

headroom.pin();    // показать элемент
headroom.unpin();  // скрыть элемент
headroom.freeze(); // остановить реакцию на прокрутку
headroom.unfreeze(); // возобновить работу
headroom.destroy(); // удалить все обработчики

Пример использования

window.addEventListener("click", () => {
  headroom.freeze();
});

Производительность

Библиотека оптимизирована для работы с прокруткой:

  • Использует requestAnimationFrame
  • Минимизирует количество перерисовок
  • Не создаёт лишних обработчиков

Это делает её подходящей даже для мобильных устройств.

Типичные сценарии использования

1. Скрывающаяся шапка сайта

Самый распространённый кейс — навигационная панель, которая:

  • скрывается при прокрутке вниз
  • появляется при прокрутке вверх

2. Фиксированные панели инструментов

Например:

  • панели фильтров
  • панели действий в админке

3. Мобильные интерфейсы

Особенно актуально для небольших экранов, где важно экономить пространство.

Ограничения и особенности

  • Не управляет стилями напрямую — требуется CSS
  • Не отслеживает горизонтальную прокрутку
  • Требует корректной структуры DOM (элемент должен быть фиксирован или позиционирован)

Сравнение с ручной реализацией

Без Headroom.js:

  • требуется писать обработчики scroll
  • отслеживать направление прокрутки
  • реализовывать debounce/throttle
  • управлять классами вручную

С Headroom.js:

  • вся логика инкапсулирована
  • остаётся только стилизация
  • повышается читаемость кода

Архитектурные особенности

  • Минималистичная реализация (~2–3 KB)
  • Не имеет зависимостей
  • Поддерживает модульные системы
  • Работает с любыми DOM-элементами

Взаимодействие с CSS

Headroom.js максимально эффективно работает в связке с:

  • transform
  • transition
  • will-change

Рекомендуемый подход:

header {
  will-change: transform;
}

Это повышает производительность анимаций.

Расширение функциональности

Возможности можно расширять за счёт:

  • кастомных колбэков
  • интеграции с фреймворками (React, Vue)
  • использования Intersection Observer совместно с Headroom

Поведение на мобильных устройствах

Особенности:

  • чувствительность прокрутки выше
  • возможны резкие изменения направления
  • важно корректно настраивать tolerance

Пример:

tolerance: {
  up: 20,
  down: 10
}

Итоговая концепция

Headroom.js — это инструмент для декларативного управления видимостью элементов на основе поведения пользователя при прокрутке. Библиотека отделяет логику от представления: JavaScript отвечает за состояние, CSS — за визуализацию.

Оглавление