Instance свойства

Popper.js работает через создание экземпляров для управления позиционированием элементов относительно их reference. Экземпляр создаётся с помощью функции createPopper(reference, popper, options), где:

  • reference — элемент DOM, относительно которого будет позиционироваться поппер.
  • popper — элемент DOM, который должен позиционироваться.
  • options — объект конфигурации, включающий стратегии позиционирования и модификаторы.

Пример базового создания экземпляра:

import { createPopper } from '@popperjs/core';

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

const popperInstance = createPopper(button, tooltip, {
  placement: 'top',
  modifiers: [
    {
      name: 'offset',
      options: {
        offset: [0, 8],
      },
    },
  ],
});

Свойства экземпляра

Экземпляр Popper.js обладает рядом методов и свойств, позволяющих управлять поведением поппера:

1. state

state — объект, содержащий текущее состояние поппера. Основные поля:

  • elements — { reference, popper } — DOM-элементы, участвующие в позиционировании.
  • options — объект опций, переданный при создании экземпляра.
  • modifiersData — данные, собранные модификаторами во время расчётов.
  • rects — размеры и позиции reference и popper.
  • placement — текущее выбранное расположение ('top', 'bottom', 'right', 'left' и их вариации 'top-start' и т.д.).
  • strategy — стратегия позиционирования ('absolute' или 'fixed').

Пример доступа к state:

console.log(popperInstance.state.placement); // 'top'
console.log(popperInstance.state.rects.popper.width); // ширина поппера

2. update()

Метод update() выполняет расчёт и обновление позиции поппера. Возвращает промис, который разрешается после применения всех изменений:

popperInstance.update().then(() => {
  console.log('Позиция обновлена');
});

update() полезен при динамическом изменении размеров reference или popper.

3. forceUpdate()

forceUpdate() выполняет немедленный пересчёт позиции, синхронно. В отличие от update(), не возвращает промис:

popperInstance.forceUpdate();

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

4. setOptions()

Метод setOptions(options) позволяет динамически изменять конфигурацию экземпляра. Все переданные настройки заменяют текущие, хотя modifiers и placement можно корректировать частично:

popperInstance.setOptions({
  placement: 'bottom',
  modifiers: [
    { name: 'offset', options: { offset: [0, 16] } },
  ],
});

После вызова setOptions() экземпляр автоматически вызывает update() для пересчёта позиции.

5. destroy()

Метод destroy() полностью удаляет экземпляр, очищает внутренние события и отменяет привязку поппера к DOM:

popperInstance.destroy();

После этого popperInstance становится неактивным, и дальнейшие вызовы методов update() или forceUpdate() не имеют эффекта.

Дополнительные свойства

  • modifiers — массив модификаторов, применяемых к текущему экземпляру. Можно получить через popperInstance.state.options.modifiers.
  • placement — удобный доступ к текущему расположению поппера без обхода state.
  • reference и popper — прямой доступ к DOM-элементам через popperInstance.state.elements.

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

Изменение позиции по событию

button.addEventListener('mouseenter', () => {
  popperInstance.setOptions({ placement: 'right' });
});

Получение размеров поппера для кастомной анимации

const popperRect = popperInstance.state.rects.popper;
tooltip.style.transformOrigin = `${popperRect.width / 2}px ${popperRect.height}px`;

Удаление экземпляра при скрытии элемента

button.addEventListener('mouseleave', () => {
  popperInstance.destroy();
});

Итог по свойствам экземпляра

Экземпляр Popper.js обеспечивает полный контроль над:

  • Расчётом и обновлением позиции (update, forceUpdate)
  • Настройками и модификаторами (setOptions)
  • Получением текущего состояния и размеров (state)
  • Управлением жизненным циклом (destroy)

Это позволяет создавать гибкие, динамические интерфейсы с точным позиционированием элементов, независимо от их размеров, положения на странице и изменений DOM.

Оглавление