Параметр fallbackPlacements

Параметр fallbackPlacements используется в Floating UI для управления стратегией позиционирования всплывающих элементов (попапов, тултипов, меню) при недостатке пространства в основной позиции. Его основная цель — гарантировать, что элемент будет корректно отображаться даже в условиях ограниченной видимой области.

Назначение

Когда основной placement (позиция относительно reference-элемента) недоступен, например, из-за выхода за границы viewport или перекрытия другими элементами, Floating UI последовательно проверяет альтернативные позиции из массива fallbackPlacements. Это предотвращает ситуации, когда всплывающий элемент оказывается обрезанным или полностью невидимым.

Синтаксис

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

computePosition(reference, floating, {
  placement: 'top',
  middleware: [
    offset(10),
    flip({
      fallbackPlacements: ['right', 'bottom', 'left']
    }),
    shift()
  ]
});
  • placement — основное предпочтение (top, bottom, left, right и их вариации с -start или -end).
  • fallbackPlacements — массив альтернативных позиций, которые проверяются в порядке следования при невозможности использовать основную.

Особенности работы

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

  2. Совместимость с flip middleware fallbackPlacements работает только в сочетании с flip. Без flip альтернативные позиции не учитываются.

  3. Поведение по умолчанию Если fallbackPlacements не указан, Floating UI использует собственный алгоритм выбора позиций, обычно это зеркальные варианты (top → bottom, left → right).

  4. Учет ограничений и смещения При каждом варианте позиционирования учитываются дополнительные middleware: offset, shift, arrow, что позволяет не только выбирать место, но и корректно позиционировать элемент относительно reference-элемента.

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

Пример 1: Простое определение fallback
flip({
  fallbackPlacements: ['bottom', 'right', 'left']
});

Здесь основное положение — top (по умолчанию задано в placement). Если top не подходит, элемент будет проверять bottom, затем right, и, наконец, left.

Пример 2: С кастомным смещением и fallback
computePosition(reference, floating, {
  placement: 'left-start',
  middleware: [
    offset(12),
    flip({
      fallbackPlacements: ['top-start', 'bottom-start', 'right-start']
    }),
    shift({ padding: 5 })
  ]
});
  • offset(12) добавляет отступ от reference-элемента.
  • flip с fallbackPlacements позволяет попробовать три альтернативные позиции.
  • shift({ padding: 5 }) гарантирует, что всплывающее окно не выйдет за границы viewport, даже если альтернативная позиция почти полностью перекрыта.

Практические советы

  • Выбор fallback-позиций стоит делать логически: сначала позиции с наименьшим нарушением интерфейса, затем более радикальные варианты.
  • Использование всех четырех направлений (top, bottom, left, right) обеспечивает максимальную надежность на устройствах с ограниченным пространством.
  • Комбинация с shift и offset позволяет создать адаптивное поведение: элемент корректно смещается и не обрезается при изменении размеров окна или скролле.
  • Порядок в массиве имеет значение — первый элемент после основного placement проверяется первым, и только при невозможности использовать его проверяется следующий.

Ограничения

  • fallbackPlacements работает только внутри middleware flip. Использование вне его контекста не имеет эффекта.
  • Если ни одно из значений fallbackPlacements не подходит, элемент может частично или полностью выйти за пределы viewport, если не подключен shift.
  • Не учитывает динамические изменения DOM после первоначального вычисления, если computePosition вызывается один раз. Для обновления позиции необходимо повторно вызывать computePosition или использовать autoUpdate.

Резюме по fallbackPlacements

  • Массив альтернативных позиций для всплывающих элементов.
  • Работает через middleware flip.
  • Упрощает создание адаптивных интерфейсов.
  • Позволяет контролировать порядок проверки и приоритетность позиций.
  • Эффективен в комбинации с shift и offset.

Использование fallbackPlacements обеспечивает предсказуемое и надежное поведение всплывающих элементов в любых условиях пространства на странице.

Оглавление