Частые ошибки и их решения

Неправильный селектор элементов Одной из самых частых ошибок является использование некорректного CSS-селектора при вызове tippy(). Например:

tippy('.tooltip-item', {
  content: 'Пример подсказки'
});

Если элементов с классом .tooltip-item нет на странице в момент вызова, тултипы не создаются, и консоль ошибок не выдаст. Решение — убедиться, что селектор существует, или использовать отложенную инициализацию после загрузки DOM:

document.addEventListener('DOMContentLoaded', () => {
  tippy('.tooltip-item', { content: 'Пример' });
});

Инициализация на динамически добавленных элементах Tippy.js по умолчанию не отслеживает элементы, добавленные после первоначальной инициализации. Частая ошибка — ожидание появления тултипов на элементах, добавленных через JavaScript после tippy(). Решение — повторный вызов tippy() или использование делегирования:

tippy(document.body, {
  content: 'Делегированный тултип',
  allowHTML: true,
  target: '.dynamic-tooltip',
  placement: 'top',
  trigger: 'mouseenter'
});

Проблемы с позиционированием

Неожиданное смещение тултипа Tippy.js использует Popper.js для позиционирования. Если контейнер имеет overflow: hidden или нестандартные CSS-трансформации (transform: scale(), translate()), тултип может смещаться. Решение — проверять родительские элементы на наличие CSS-свойств, влияющих на позицию, и при необходимости использовать опцию appendTo:

tippy('.tooltip-item', {
  content: 'Тултип вне контейнера',
  appendTo: () => document.body
});

Неверная установка placement Иногда placement не работает ожидаемо из-за отсутствия места. Для корректной работы лучше использовать комбинацию placement и flip:

tippy('.tooltip-item', {
  content: 'Позиция с флипом',
  placement: 'top',
  flip: true
});

Ошибки при работе с контентом

Передача функции вместо строки Некорректная передача функции контента может приводить к неожиданным результатам:

// Некорректно
tippy('.tooltip-item', {
  content: () => 'Динамический контент'
});

Правильный способ — использование опции allowHTML и возврат DOM-элемента или строки:

tippy('.tooltip-item', {
  content: document.createElement('div'), // или строка
  allowHTML: true
});

Использование HTML без allowHTML При вставке HTML в content без allowHTML: true код будет отображаться как текст. Решение:

tippy('.tooltip-item', {
  content: '<strong>Жирный текст</strong>',
  allowHTML: true
});

Ошибки с триггерами и взаимодействием

Неправильная комбинация триггеров Tippy.js поддерживает click, mouseenter, focus и их комбинации. Если назначить click и одновременно mouseenter, тултип может вести себя непредсказуемо. Оптимально выбирать один основной триггер или использовать делегирование.

Не закрывается при клике вне Ошибка возникает при использовании interactive: true без правильной настройки hideOnClick. Для корректного закрытия:

tippy('.tooltip-item', {
  content: 'Интерактивный тултип',
  interactive: true,
  hideOnClick: true
});

Управление состоянием тултипов

Попытка изменить контент после инициализации без ссылки на экземпляр Tippy.js возвращает массив или объект экземпляров. Ошибка — попытка вызвать setContent на селекторе напрямую:

// Некорректно
tippy('.tooltip-item').setContent('Новый текст');

Правильный способ:

const tip = tippy('.tooltip-item')[0]; // первый экземпляр
tip.setContent('Новый текст');

Ошибка с destroy и unmount Попытка уничтожить тултип на неинициализированном элементе вызовет ошибку. Всегда проверять существование экземпляра:

const tip = tippy('.tooltip-item')[0];
if (tip) tip.destroy();

Проблемы с производительностью

Создание слишком большого количества тултипов Инициализация Tippy.js на сотнях элементов без делегирования приводит к задержкам и падению FPS. Решение — использовать делегирование или ленивую инициализацию через события:

tippy(document.body, {
  content: 'Делегированный тултип',
  target: '.tooltip-item',
  delay: 100
});

Чрезмерное использование анимаций Сложные анимации для каждого тултипа могут нагрузить браузер. Рекомендуется использовать стандартные эффекты fade или scale и минимизировать кастомные CSS-анимации для больших списков элементов.

Ошибки в конфигурации глобальных опций

Неверная установка defaultProps Tippy.js позволяет задавать глобальные опции через tippy.setDefaultProps. Ошибка — попытка установить свойства после инициализации тултипов, что не повлияет на уже созданные экземпляры. Решение — задавать глобальные настройки до первой инициализации:

tippy.setDefaultProps({
  placement: 'bottom',
  animation: 'fade'
});

Конфликт локальных и глобальных опций Если локальные опции противоречат глобальным, Tippy.js использует приоритет локальных. Ошибкой считается ожидание, что глобальные настройки изменят поведение уже созданного тултипа. Решение — корректно комбинировать опции и проверять приоритеты.

Эта подборка охватывает самые распространённые ошибки при работе с Tippy.js и способы их устранения, позволяя создавать стабильные, предсказуемые и производительные тултипы.

Оглавление