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

Переход с версии 5.x на 6.x в Tippy.js сопровождается существенной переработкой внутренней архитектуры. Ключевое изменение — более тесная интеграция с библиотекой Popper второго поколения (Popper 2), что влияет на позиционирование, модификаторы и производительность.

В версии 5 использовался Popper.js v1, который имел ограничения по кастомизации и расширяемости. В 6.x:

  • полностью заменён движок позиционирования
  • введена система модификаторов Popper 2
  • улучшена обработка переполнения (overflow) и границ (boundaries)

Это означает, что многие параметры, связанные с позиционированием, изменили поведение или были переименованы.

Изменения в API

Удалённые и переименованные опции

Некоторые параметры конфигурации были удалены или заменены:

  • flipBehavior → заменён на fallbackPlacements
  • boundary → теперь задаётся через popperOptions
  • distance → заменён на offset

Пример миграции:

5.x

tippy(element, {
  distance: 10,
  flipBehavior: ['top', 'bottom']
});

6.x

tippy(element, {
  offset: [0, 10],
  popperOptions: {
    modifiers: [
      {
        name: 'flip',
        options: {
          fallbackPlacements: ['top', 'bottom']
        }
      }
    ]
  }
});

Изменение поведения offset

В версии 5 distance задавал только отступ по основной оси. В 6.x offset принимает массив:

offset: [skidding, distance]
  • skidding — смещение по поперечной оси
  • distance — смещение по основной оси

Это даёт более гибкий контроль над положением тултипа.

Новая система popperOptions

В версии 6 добавлена возможность напрямую управлять Popper через popperOptions.

Пример:

tippy(element, {
  popperOptions: {
    modifiers: [
      {
        name: 'preventOverflow',
        options: {
          padding: 8
        }
      }
    ]
  }
});

Это заменяет множество старых опций и даёт доступ к низкоуровневой настройке позиционирования.

Изменения в работе с темами

В версии 5 темы подключались через CSS-классы, но структура классов была менее стандартизирована.

В 6.x:

  • введён единый формат классов
  • темы стали более предсказуемыми
  • улучшена изоляция стилей

Пример:

tippy(element, {
  theme: 'light'
});

CSS:

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

Обновлённая система плагинов

В версии 6 появилась полноценная система плагинов.

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

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

tippy(element, {
  plugins: [followCursor],
  followCursor: true
});

Отличия от 5.x

В 5.x подобная функциональность часто была встроенной или реализовывалась через хаки. В 6.x:

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

Изменения в обработке событий

Хуки жизненного цикла

Некоторые хуки были переработаны:

  • onShow
  • onHide
  • onMount
  • onDestroy

Теперь они работают более последовательно и синхронизированы с Popper 2.

Пример:

tippy(element, {
  onShow(instance) {
    console.log('Показ', instance);
  }
});

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

В версии 6:

  • убраны устаревшие анимации
  • добавлена поддержка CSS-переходов через data-state
  • улучшена производительность

Пример кастомной анимации:

.tippy-box[data-state='visible'] {
  opacity: 1;
  transform: scale(1);
}

.tippy-box {
  opacity: 0;
  transform: scale(0.95);
  transition: all 0.2s ease;
}

Работа с HTML-контентом

Поведение allowHTML осталось, но стало более безопасным:

tippy(element, {
  content: '<strong>Текст</strong>',
  allowHTML: true
});

Рекомендуется использовать проверенные источники HTML, так как библиотека не выполняет санитизацию.

Изменения в trigger и взаимодействиях

В 6.x улучшена обработка событий:

  • лучше работает mouseenter / focus
  • исправлены баги с мобильными устройствами
  • добавлена поддержка комбинированных триггеров

Пример:

tippy(element, {
  trigger: 'mouseenter focus click'
});

Улучшения производительности

Ключевые оптимизации:

  • ленивое создание Popper-инстансов
  • уменьшение количества перерисовок
  • оптимизация DOM-операций

Это особенно заметно при большом количестве тултипов на странице.

Изменения в методах экземпляра

Методы остались схожими, но поведение стало более предсказуемым:

const instance = tippy(element);

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

В 6.x:

  • методы работают быстрее
  • устранены гонки состояний
  • улучшена синхронизация с DOM

Удалённые возможности

Некоторые устаревшие функции были полностью удалены:

  • IE11 больше не поддерживается
  • устаревшие опции Popper v1
  • неявные глобальные настройки

Это позволило упростить кодовую базу и уменьшить размер библиотеки.

Изменения в импорте и сборке

В 6.x улучшена поддержка модульных сборщиков:

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

Также:

  • улучшена поддержка tree-shaking
  • уменьшен размер бандла
  • добавлены ESM-сборки

Практическая стратегия миграции

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

npm install tippy.js@6

2. Проверка опций

Необходимо:

  • заменить устаревшие параметры (distance, flipBehavior)
  • перенести настройки в popperOptions

3. Проверка CSS

  • обновить селекторы (.tippy-box)
  • адаптировать темы
  • проверить анимации

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

Если использовались дополнительные возможности:

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

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

Особое внимание:

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

Частые проблемы при миграции

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

Причина: изменения в Popper 2 Решение: использовать popperOptions и модификаторы

Сломанные отступы

Причина: переход с distance на offset Решение: корректно задать массив [x, y]

Не работают дополнительные функции

Причина: отсутствие плагинов Решение: явно подключить нужные плагины

Стили не применяются

Причина: изменена структура DOM Решение: обновить CSS-селекторы (.tippy-box, data-theme)

Глубокая интеграция с Popper 2

Возможности, появившиеся благодаря обновлению:

  • кастомные модификаторы
  • точный контроль над границами
  • адаптивное позиционирование

Пример кастомного модификатора:

tippy(element, {
  popperOptions: {
    modifiers: [
      {
        name: 'offset',
        options: {
          offset: [10, 20]
        }
      }
    ]
  }
});

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

В 6.x структура тултипа стала более строгой:

<div class="tippy-box" data-theme="light">
  <div class="tippy-content">
    Контент
  </div>
</div>

Это важно учитывать при кастомизации и работе с CSS.

Итоговые различия между 5.x и 6.x

Ключевые направления изменений:

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

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

Оглавление