Обновление с версии 4.x

Переход с версии 4.x на более новые версии Tippy.js сопровождается значительными изменениями внутренней архитектуры. Основное отличие заключается в переходе на модульную структуру и более тесную интеграцию с Popper.js версии 2.

В версии 4.x библиотека была монолитной: весь функционал поставлялся «из коробки», включая анимации, темы и плагины. В новых версиях:

  • ядро стало легче
  • дополнительные возможности вынесены в плагины
  • появилась поддержка tree-shaking
  • улучшена производительность за счёт оптимизации DOM-операций

Это означает, что теперь подключение Tippy.js требует более явного управления зависимостями.

Изменение системы импорта

В версии 4.x использовался глобальный или CommonJS/UMD подход:

import tippy from 'tippy.js';
import 'tippy.js/dist/tippy.css';

В новых версиях применяется современный ES-модульный синтаксис с поддержкой плагинов:

import tippy from 'tippy.js';
import 'tippy.js/dist/tippy.css';

На первый взгляд код похож, однако:

  • дополнительные функции (например, followCursor, animateFill) теперь требуют отдельного импорта
  • отсутствует автоматическое включение всех возможностей

Пример подключения плагина:

import tippy, { followCursor } from 'tippy.js';

tippy('.btn', {
  followCursor: true,
  plugins: [followCursor],
});

Работа с Popper.js v2

В версии 4.x использовалась более старая версия Popper.js. Обновление принесло:

  • новую систему модификаторов
  • улучшенную точность позиционирования
  • более гибкое управление поведением всплывающих элементов

Старые свойства, связанные с позиционированием, могли измениться или быть удалены.

Пример изменения:

Версия 4.x:

tippy('.btn', {
  flip: true,
});

Новая версия:

tippy('.btn', {
  popperOptions: {
    modifiers: [
      {
        name: 'flip',
        enabled: true,
      },
    ],
  },
});

Изменения в API опций

Многие опции были либо переименованы, либо переработаны.

Удалённые или изменённые параметры

  • performance — удалён
  • arrowType — заменён на кастомный HTML или SVG
  • flipBehavior — заменён системой модификаторов Popper

Новые подходы

Теперь многие настройки требуют более явной конфигурации:

tippy('.btn', {
  placement: 'top',
  offset: [0, 10],
});

Работа со стрелкой (arrow)

В версии 4.x стрелка задавалась строкой:

arrow: true

или:

arrowType: 'round'

В новых версиях:

  • используется либо boolean, либо кастомный элемент
  • стандартные стили упрощены

Пример:

tippy('.btn', {
  arrow: true,
});

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

tippy('.btn', {
  arrow: '<svg>...</svg>',
});

Переход на плагины

Одно из ключевых изменений — отказ от встроенного функционала в пользу плагинов.

В версии 4.x:

tippy('.btn', {
  followCursor: true,
});

В новой версии:

import tippy, { followCursor } from 'tippy.js';

tippy('.btn', {
  followCursor: true,
  plugins: [followCursor],
});

Без подключения плагина опция не будет работать.

Изменения в анимациях

В версии 4.x анимации были встроены и управлялись через строковые значения:

animation: 'fade'

В новых версиях:

  • анимации упрощены
  • многие эффекты удалены
  • рекомендуется использовать CSS-анимации

Пример:

tippy('.btn', {
  animation: 'scale',
});

Для кастомных анимаций:

.tippy-box[data-animation='custom'] {
  transition: transform 0.2s ease;
}

Обработка событий жизненного цикла

События остались, но были стандартизированы и расширены.

Пример:

tippy('.btn', {
  onShow(instance) {
    console.log('Показ');
  },
  onHide(instance) {
    console.log('Скрытие');
  },
});

Новые версии обеспечивают:

  • более предсказуемый порядок вызовов
  • улучшенную работу с асинхронностью

Изменения в темах (themes)

В версии 4.x темы были частью библиотеки.

В новых версиях:

  • темы минималистичны
  • пользователь чаще создаёт собственные стили

Пример:

tippy('.btn', {
  theme: 'light',
});

CSS:

.tippy-box[data-theme~='light'] {
  background-color: #fff;
  color: #000;
}

Работа с содержимым (content)

Синтаксис в целом сохранился, но стал более гибким.

Строка:

tippy('.btn', {
  content: 'Подсказка',
});

HTML:

tippy('.btn', {
  content: '<strong>HTML</strong>',
  allowHTML: true,
});

Функция:

tippy('.btn', {
  content(reference) {
    return reference.getAttribute('data-title');
  },
});

Изменения в поведении триггеров

Триггеры (trigger) остались, но логика стала более строгой.

tippy('.btn', {
  trigger: 'mouseenter focus',
});

Особенности:

  • улучшена поддержка мобильных устройств
  • корректнее обрабатываются события pointer

Удаление deprecated-функций

При обновлении важно учитывать удалённые возможности:

  • старые анимации
  • некоторые устаревшие параметры Popper
  • неиспользуемые внутренние методы

Использование устаревших опций больше не вызывает предупреждений — они просто игнорируются.

Миграция: пошаговый подход

1. Обновление зависимостей

npm install tippy.js@latest

2. Проверка импорта

  • убрать устаревшие require
  • перейти на ES Modules

3. Подключение плагинов

Любые расширенные функции необходимо импортировать отдельно.

4. Обновление конфигурации Popper

  • заменить устаревшие параметры на popperOptions
  • проверить позиционирование

5. Перепроверка стилей

  • обновить CSS
  • адаптировать темы

6. Тестирование поведения

  • hover
  • focus
  • touch-события
  • динамический контент

Производительность и оптимизация

Новые версии обеспечивают:

  • меньший размер бандла
  • возможность tree-shaking
  • более эффективное позиционирование
  • меньшее количество reflow/repaint

Для максимальной эффективности:

  • подключать только необходимые плагины
  • избегать тяжёлого HTML в content
  • использовать делегирование при большом количестве элементов

Типичные ошибки при обновлении

1. Плагин не подключён

followCursor: true // не работает

Решение:

plugins: [followCursor]

2. Старые параметры Popper

flipBehavior: 'clockwise'

Решение — использовать modifiers.

3. Сломанные стили

Причина:

  • изменения в DOM-структуре Tippy

Решение:

  • обновить CSS-селекторы

4. Проблемы с HTML-контентом

content: '<b>text</b>' // не работает

Решение:

allowHTML: true

Изменения DOM-структуры

Структура тултипа стала более предсказуемой:

<div class="tippy-box">
  <div class="tippy-content"></div>
</div>

Это упрощает:

  • кастомизацию
  • стилизацию
  • отладку

Совместимость с фреймворками

Новые версии лучше интегрируются с:

  • React
  • Vue
  • Svelte

Благодаря:

  • отсутствию скрытых зависимостей
  • предсказуемому API
  • улучшенной работе с виртуальным DOM

Управление экземплярами

Создание экземпляра:

const instance = tippy('.btn');

Работа с ним:

instance.show();
instance.hide();
instance.destroy();

В новых версиях:

  • API стал чище
  • меньше побочных эффектов
  • лучше управление памятью

Асинхронный контент

Поддержка асинхронности стала удобнее:

tippy('.btn', {
  async content() {
    const data = await fetch('/api').then(r => r.text());
    return data;
  },
});

Безопасность

Добавлен более строгий контроль HTML:

  • allowHTML по умолчанию выключен
  • снижены риски XSS

Итоговые отличия

  • модульность вместо монолита
  • обязательное использование плагинов
  • переход на Popper v2
  • упрощённый, но более гибкий API
  • улучшенная производительность
  • более строгая и предсказуемая архитектура
Оглавление