Структура документации

Floating UI — это библиотека для управления позиционированием плавающих элементов на веб-странице. Она предоставляет инструменты для создания тултипов, дропдаунов, поповер-окошек и других элементов интерфейса, которые должны быть динамически привязаны к определённой цели (anchor). Библиотека фокусируется на точности позиции, автоматическом смещении и адаптивности к изменениям viewport.

Floating и reference элементы

В основе работы лежат два ключевых понятия:

  • Reference элемент – это элемент DOM, к которому привязан плавающий элемент. Он определяет исходную точку отсчёта.
  • Floating элемент – это элемент, который будет позиционироваться относительно reference.

Floating UI вычисляет координаты x и y для плавающего элемента исходя из позиции reference и правил смещения.

Контроль позиции

Позиционирование реализуется через middleware — функции, которые обрабатывают вычисления и корректируют координаты. Основные middleware:

  • offset — добавляет смещение по осям X и Y, чтобы плавающий элемент не перекрывал reference.
  • flip — изменяет сторону появления элемента, если на исходной стороне не хватает места в viewport.
  • shift — корректирует позицию плавающего элемента, чтобы он полностью помещался в видимую область.
  • autoPlacement — автоматически выбирает оптимальное направление появления, комбинируя flip и shift.

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

import { computePosition, offset, flip, shift } from '@floating-ui/dom';

const reference = document.querySelector('#button');
const floating = document.querySelector('#tooltip');

computePosition(reference, floating, {
  middleware: [offset(10), flip(), shift({ padding: 5 })],
}).then(({ x, y }) => {
  Object.assign(floating.style, {
    left: `${x}px`,
    top: `${y}px`,
  });
});

Управление размерами и адаптивность

Floating UI позволяет динамически управлять размерами элементов:

  • size middleware — изменяет размеры floating-элемента в зависимости от доступного пространства.
  • Поддержка maxWidth и maxHeight через вычисляемые свойства.
  • Совместимость с реактивными фреймворками позволяет обновлять размеры и позицию при изменении содержимого.

События и реактивность

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

  • autoUpdate — следит за изменением размеров reference или floating элементов и автоматически пересчитывает позицию.
  • Можно подключать scroll и resize listeners, чтобы плавающие элементы оставались корректно позиционированными при прокрутке или изменении размера окна.

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

import { autoUpdate } from '@floating-ui/dom';

const cleanup = autoUpdate(reference, floating, () => {
  computePosition(reference, floating, {
    middleware: [offset(10), flip(), shift()],
  }).then(({ x, y }) => {
    Object.assign(floating.style, { left: `${x}px`, top: `${y}px` });
  });
});

// Для отключения слежения
cleanup();

Позиционирование в сложных структурах DOM

Floating UI умеет корректно работать в следующих сценариях:

  • Плавающие элементы внутри scrollable containers — middleware shift корректирует положение с учётом прокрутки.
  • Portals и модальные окна — можно рендерить floating элементы вне обычного DOM-дерева reference, сохраняя точное позиционирование.
  • Комбинированные middleware — позволяет создавать сложные сценарии, например тултип с ограничением по ширине и автофлипом при нехватке места.

Интеграция с фреймворками

  • В React существует отдельный пакет @floating-ui/react, который предоставляет хуки useFloating, упрощающие привязку позиции к компоненту.
  • В Vue можно использовать кастомные директивы или composables для реактивного слежения.
  • В Svelte применяется реактивная подписка на координаты, обновляемые computePosition и autoUpdate.

Ключевые преимущества

  • Высокая точность вычислений позиции, даже при сложной структуре DOM.
  • Гибкость через middleware, позволяющая комбинировать смещение, флип и сдвиг под конкретные задачи.
  • Реактивное обновление позиции и размеров при изменениях viewport, содержимого или скролла.
  • Независимость от CSS-фреймворков, работа с чистым DOM и современными фреймворками.

Практические рекомендации

  • Всегда использовать middleware shift и flip для элементов, которые должны оставаться видимыми.
  • При динамически изменяемом содержимом подключать autoUpdate.
  • Для сложных интерфейсов с модальными окнами или порталами корректно задавать контейнер для floating элемента.
  • Контролировать z-index и pointer-events через CSS, чтобы floating элемент не блокировал взаимодействие с другими элементами.

Floating UI позволяет создавать надёжные, адаптивные интерфейсы с плавающими элементами, обеспечивая точное позиционирование, высокую гибкость и совместимость с современными фронтенд-фреймворками.

Оглавление