Одной из самых распространённых проблем является ситуация, когда при запуске тура элементы страницы не подсвечиваются, а тултипы либо не появляются, либо отображаются в неправильном месте. Основные причины:
Неправильный селектор элемента: Intro.js
работает с CSS-селекторами, указанными в атрибутах
data-intro и data-step. Если селектор не
соответствует существующему элементу, шаг будет игнорироваться.
Решение: проверить правильность селектора через
document.querySelector или
document.querySelectorAll.
Элемент не присутствует в DOM на момент инициализации: часто возникает при динамической подгрузке контента (AJAX, React, Vue). Решение: запускать Intro.js после полной отрисовки элементов. В SPA-фреймворках стоит использовать коллбэк после рендеринга.
Скрытые или неактивные элементы: если элемент
имеет display: none или visibility: hidden,
Intro.js не сможет правильно его подсветить. Решение:
убедиться, что элемент видим на странице и имеет ненулевую ширину и
высоту.
Причины преждевременного завершения тура:
Конфликты с другими библиотеками: некоторые
модальные окна или скрипты перезаписывают DOM или вызывают событие
click, что может завершить Intro.js.
Решение: использовать события Intro.js
(onbeforechange, onafterchange) для контроля
поведения и предотвращения нежелательного закрытия.
Неправильная настройка exitOnOverlayClick
или exitOnEsc: по умолчанию клик на оверлей и
клавиша ESC закрывают тур. Решение: для критических
туров установить
introJs().setOptions({ exitOnOverlayClick: false, exitOnEsc: false }).
Ошибки в логике шагов: пропущенный шаг или
некорректный data-step может привести к сбою.
Решение: проверить последовательность шагов и
убедиться, что data-step идут по порядку без
пропусков.
Intro.js автоматически позиционирует подсказки вокруг элементов, но иногда они перекрывают контент или отображаются за пределами видимой области.
Неправильные значения
data-position: допустимые варианты –
top, right, bottom,
left. Некорректное значение игнорируется.
Решение: явно указывать допустимое значение и проверять
визуально на разных разрешениях.
Элементы близко к краю окна: подсказка может
выйти за пределы экрана. Решение: использовать опцию
tooltipPosition или динамически вычислять положение с
помощью события onbeforechange.
Стили CSS, влияющие на размеры или overflow:
родительские контейнеры с overflow: hidden могут обрезать
тултипы. Решение: либо изменить CSS контейнера, либо
использовать position: fixed для подсказок через
переопределение стилей Intro.js.
Не подключен JS или CSS Intro.js: отсутствие
файлов библиотеки приведёт к полной неработоспособности.
Решение: убедиться, что подключены оба файла и они
загружаются до вызова introJs().start().
Неправильный порядок подключения скриптов: если
вызов introJs() происходит до загрузки DOM или до
подключения библиотеки. Решение: вызывать
introJs().start() внутри DOMContentLoaded или
использовать defer в подключении скриптов.
Конфликты с другими скриптами: повторное подключение Intro.js или конфликт версий может вызвать ошибки в консоли. Решение: подключать библиотеку один раз и проверять версию.
В современных веб-приложениях элементы могут добавляться динамически. Если они не присутствуют в момент старта тура:
Шаг пропускается или выдает ошибку.
Решение: использовать метод refresh()
после добавления элементов в DOM, либо запускать Intro.js после полной
загрузки динамического контента.
Не срабатывает на скрытых вкладках или
аккордеонах. Решение: перед вызовом Intro.js
раскрывать вкладки через скрипт и использовать
onbeforechange для динамического показа контента.
Скролл не учитывает фиксированные шапки и
панели: подсказка может скрываться за фиксированным header.
Решение: добавлять отступ через кастомный CSS или
использовать событие onafterchange, чтобы поднимать
страницу вручную с учётом высоты шапки.
Прыжки при смене шага: возникает при изменении DOM между шагами. Решение: фиксировать размеры контейнеров и избегать резких изменений layout во время тура.
introJs().setOption('showStepNumbers', true).start();onbeforechange и
onafterchange для логирования текущего шага и состояния
DOM.introJs().refresh(); после изменений DOM.disableInteraction: true для шагов, где
пользователь не должен прерывать тур.getBoundingClientRect() перед стартом тура.Эти методы позволяют выявить большинство проблем с подсветкой, позиционированием и поведением шагов, обеспечивая стабильную работу интерактивных туров на страницах любого уровня сложности.