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

Библиотека Tippy.js использует механизм позиционирования на основе Popper (Popper.js), который рассчитывает координаты всплывающего элемента относительно целевого. Основная цель — обеспечить корректное размещение tooltip’а независимо от размеров окна, прокрутки и доступного пространства.

Ключевой параметр управления размещением — placement. Он определяет, с какой стороны относительно целевого элемента будет отображаться всплывающая подсказка.

Параметр placement

Основные значения

Параметр placement принимает строку, определяющую направление:

  • top
  • bottom
  • left
  • right

Пример:

tippy(button, {
  placement: 'top'
});

Вариации с выравниванием

Каждое направление можно уточнить с помощью суффиксов:

  • -start — выравнивание по началу
  • -end — выравнивание по концу

Полный список:

  • top-start
  • top-end
  • bottom-start
  • bottom-end
  • left-start
  • left-end
  • right-start
  • right-end

Пример:

tippy(button, {
  placement: 'right-start'
});

Поведение

  • Без суффикса tooltip центрируется относительно элемента
  • start и end зависят от направления текста (LTR/RTL)
  • При нехватке места положение может измениться (если включён flip)

Автоматическое изменение положения (flip)

Назначение

Если заданное положение невозможно из-за ограниченного пространства, Tippy автоматически изменяет его.

tippy(button, {
  placement: 'top',
  flip: true
});

Расширенная настройка через popperOptions

tippy(button, {
  popperOptions: {
    modifiers: [
      {
        name: 'flip',
        options: {
          fallbackPlacements: ['bottom', 'right']
        }
      }
    ]
  }
});

Особенности

  • Порядок fallback влияет на приоритет
  • По умолчанию используется логичная последовательность (например, top → bottom)

Ограничение выхода за границы (preventOverflow)

Назначение

Предотвращает выход tooltip’а за пределы видимой области.

tippy(button, {
  popperOptions: {
    modifiers: [
      {
        name: 'preventOverflow',
        options: {
          boundary: 'viewport'
        }
      }
    ]
  }
});

Варианты boundary

  • viewport — границы окна
  • window
  • scrollParent
  • DOM-элемент

Дополнительные параметры

options: {
  padding: 8
}

Определяет отступ от границ.

Смещение (offset)

Назначение

Позволяет точно настроить расстояние между элементом и tooltip’ом.

tippy(button, {
  offset: [0, 10]
});

Структура

offset: [skidding, distance]
  • skidding — смещение вдоль оси элемента
  • distance — расстояние от элемента

Примеры

// Смещение вниз на 15px
offset: [0, 15]

// Смещение вправо и вниз
offset: [10, 20]

Привязка к курсору (followCursor)

Назначение

Tooltip следует за курсором мыши.

tippy(button, {
  followCursor: true
});

Варианты

  • true — полностью следует
  • horizontal — только по X
  • vertical — только по Y
  • initial — фиксируется в начальной позиции

Интерактивное позиционирование (interactive)

Назначение

Позволяет взаимодействовать с содержимым tooltip’а (например, кнопки, ссылки).

tippy(button, {
  interactive: true
});

Влияние на размещение

  • Tooltip остаётся открытым при наведении
  • Используется дополнительная зона удержания (interactiveBorder)
interactiveBorder: 10

Стрелка (arrow) и её позиционирование

Включение стрелки

tippy(button, {
  arrow: true
});

Особенности

  • Стрелка автоматически позиционируется Popper
  • Смещение зависит от placement

Кастомная стрелка

tippy(button, {
  arrow: '<div class="custom-arrow"></div>'
});

Контейнер размещения (appendTo)

Назначение

Определяет, куда в DOM добавляется tooltip.

tippy(button, {
  appendTo: document.body
});

Варианты

  • document.body — стандартное поведение
  • 'parent' — внутри родителя
  • пользовательская функция

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

  • Может устранить проблемы с overflow: hidden
  • Влияет на stacking context

Фиксированное позиционирование (strategy)

Варианты

tippy(button, {
  popperOptions: {
    strategy: 'fixed'
  }
});
  • absolute — по умолчанию
  • fixed — относительно viewport

Когда использовать fixed

  • внутри скроллируемых контейнеров
  • при сложных layout’ах

Привязка к кастомному элементу (getReferenceClientRect)

Назначение

Позволяет позиционировать tooltip относительно произвольных координат.

tippy(document.body, {
  getReferenceClientRect: () => ({
    width: 0,
    height: 0,
    top: 100,
    bottom: 100,
    left: 200,
    right: 200
  })
});

Применение

  • контекстные меню
  • подсказки в canvas
  • виртуальные элементы

Динамическое обновление позиции

Метод setProps

instance.setProps({
  placement: 'bottom'
});

Метод popperInstance.update()

instance.popperInstance.update();

Используется при изменении размеров или контента.

Обработка скролла и ресайза

Tippy автоматически отслеживает:

  • прокрутку
  • изменение размеров окна

Однако в сложных случаях можно вручную обновить:

window.addEventListener('scroll', () => {
  instance.popperInstance.update();
});

Параметры для тонкой настройки Popper

Полный пример

tippy(button, {
  popperOptions: {
    placement: 'top',
    modifiers: [
      {
        name: 'offset',
        options: {
          offset: [0, 12]
        }
      },
      {
        name: 'flip',
        options: {
          fallbackPlacements: ['bottom', 'right']
        }
      },
      {
        name: 'preventOverflow',
        options: {
          boundary: 'viewport',
          padding: 10
        }
      }
    ]
  }
});

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

Важные свойства

  • position
  • overflow
  • transform
  • z-index

Проблемные случаи

  • overflow: hidden может обрезать tooltip
  • transform создаёт новый контекст позиционирования
  • z-index влияет на перекрытие

Рекомендации по выбору параметров

  • Использовать placement как базовую настройку
  • Добавлять offset для визуального баланса
  • Включать flip для адаптивности
  • Настраивать preventOverflow для сложных интерфейсов
  • Применять appendTo: document.body при проблемах с контейнерами
  • Использовать fixed стратегию в сложных layout’ах

Типичные ошибки

Неправильное выравнивание

  • Причина: неверный placement
  • Решение: использовать start/end

Tooltip обрезается

  • Причина: overflow: hidden
  • Решение: appendTo: document.body

Неправильная позиция при скролле

  • Причина: вложенные контейнеры
  • Решение: strategy: fixed

Смещение выглядит странно

  • Причина: неверный offset
  • Решение: проверить порядок [skidding, distance]

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

Параметры размещения не работают изолированно:

  • placement задаёт базовое направление
  • flip может его изменить
  • preventOverflow корректирует координаты
  • offset добавляет финальное смещение

Итоговая позиция — результат последовательной обработки этих модификаторов.

Оглавление