Параметры размещения (placement)

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

<основное направление>-<вариация>
  • Основные направления: top, bottom, left, right.
  • Вариации (alignment): start, end, либо отсутствие вариации (центрирование).

Примеры значений:

  • top — элемент размещается над reference-элементом, по центру.
  • bottom-start — элемент размещается под reference-элементом, выравнивание по левому краю.
  • right-end — элемент справа от reference-элемента, выравнивание по нижнему краю.

Если вариация не указана, по умолчанию происходит центрирование по основной оси.

Влияние placement на позиционирование

Параметр placement тесно связан с логикой offset и middleware в Floating UI. Влияние можно разложить на следующие аспекты:

  1. Направление смещения

    • top и bottom изменяют вертикальное расположение.
    • left и right влияют на горизонтальное расположение.

  2. Вариация (start / end)

    • start выравнивает флоатинг по началу оси reference-элемента.
    • end — по концу оси.
    • Центрирование происходит при отсутствии вариации.

  3. Совместимость с flip middleware Когда указано фиксированное placement, middleware flip может менять направление при нехватке места. Например, top-start может автоматически превратиться в bottom-start, если сверху нет свободного пространства.

Принципы выбора placement

  • Контекст интерфейса Выбор зависит от того, с какой стороны reference-элемента пользователь ожидает увидеть всплывающее окно. Например, выпадающие меню чаще всего используют bottom-start.

  • Доступное пространство При ограниченном пространстве лучше использовать комбинацию placement с middleware flip и shift, чтобы предотвратить обрезку содержимого.

  • Направление текста Для RTL интерфейсов значения start и end меняются: start соответствует правому краю, end — левому.

Практическая работа с placement

Простейший пример использования Floating UI с указанием placement:

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

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

computePosition(reference, floating, {
  placement: 'top-start',
  middleware: [offset(10), flip(), shift({ padding: 5 })],
}).then(({ x, y }) => {
  Object.assign(floating.style, {
    left: `${x}px`,
    top: `${y}px`,
  });
});
  • placement: 'top-start' — всплывающий элемент появляется над кнопкой, выравнивание по левому краю.
  • offset(10) — добавляет отступ от reference-элемента.
  • flip() — позволяет менять направление при нехватке места.
  • shift({ padding: 5 }) — корректирует позицию, чтобы элемент не выходил за границы viewport.

Разбор всех возможных значений

Основное направление Без вариации Вариация start Вариация end
top Центр над элементом Слева над элементом Справа над элементом
bottom Центр под элементом Слева под элементом Справа под элементом
left Центр слева Сверху слева Снизу слева
right Центр справа Сверху справа Снизу справа

Рекомендации по использованию

  • Для меню и тултипов чаще всего используют bottom-start или top-start.
  • Для попапов слева/справа важна вариация для точного выравнивания с reference-элементом.
  • Всегда сочетать placement с middleware flip и shift, чтобы флоатинг корректно адаптировался к размерам окна.
  • В сложных интерфейсах можно динамически менять placement в зависимости от видимой области или положения скролла.

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

Оглавление