Справочник API

Навигационные стрелки. true — поиск по стандартным классам и создание недостающих кнопок внутри root, объект — кастомная настройка. Созданные кнопки удаляются при отключении опции или destroy().

Пользовательские элементы сохраняются после destroy(). Кнопки могут находиться вне слайдера.

const slider = new Tvist('.slider', {
  arrows: { prev: '#prev', next: '#next', addIcons: false },
})

Примеры навигации.

Вложенные настройки →

Если true, высота слайдов определяется их содержимым (для вертикального направления). Рекомендуется perPage: 1.

Автопрокрутка слайдов.

• false — выключена (по умолчанию)
• true — включена с задержкой 3000мс и дефолтными настройками
• number — включена с указанной задержкой в миллисекундах
• AutoplayOptions — полный контроль: delay, pauseOnHover, pauseOnFocus, pauseOnInteraction, disableOnInteraction, waitForVideo

Число задаёт задержку в миллисекундах. Управлять работающей автопрокруткой можно через slider.autoplay; без активного модуля это свойство возвращает undefined.

const slider = new Tvist('.slider', {
  loop: true,
  autoplay: { delay: 3000, pauseOnHover: true },
})
slider.autoplay?.pause()
slider.autoplay?.resume()

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

Вложенные настройки →

Если true, ширина слайдов определяется их содержимым (не задаётся слайдером). Рекомендуется perPage: 1.

Адаптивные настройки по breakpoints. Ключ - ширина экрана в пикселях

Ключ — максимальная ширина в пикселях. При совпадении нескольких условий применяется наименьший подходящий breakpoint; за пределами условий восстанавливаются базовые опции.

const slider = new Tvist('.slider', {
  perPage: 3,
  breakpoints: {
    1024: { perPage: 2 },
    640: { perPage: 1 },
  },
})

Подробности breakpoints · Живой пример.

База для расчёта breakpoints

Специфичные фиксы для браузеров

Вложенные настройки →

Центрирование слайдов.

• true — центрирует активный слайд в viewport (режим “active”).
• Объект { active?, focus?, justify? } — тонкая настройка:
  • active: true — центрирует активный слайд всегда, включая края (аналог center: true)
  • focus: true — центрирует активный слайд, когда возможно; у краёв без пустот (как Splide focus:center)
  • justify: true — визуально центрирует все слайды когда locked (как justify-content: center)

Примеры центрирования.

Вложенные настройки →

Настройки cube эффекта

Вложенные настройки →

Режим отладки: вывод предупреждений в консоль (arrows not found, container not found и т.д.)

Направление прокрутки слайдера

Включить перетаскивание слайдов. ‘free’ - свободная прокрутка без привязки к слайдам

const slider = new Tvist('.slider', {
  drag: 'free',
  freeSnap: true,
  flickPower: 600,
})

Свободное перетаскивание.

Множитель скорости перетаскивания

Эффект перехода между слайдами

Включить/выключить слайдер. При false слайдер не инициализируется (статичный контент)

При false слайдер показывает статичный контент. Управлять состоянием можно через enable(), disable() и updateOptions({ enabled }).

Настройки fade эффекта

Вложенные настройки →

Фиксированная высота слайда (px или CSS). Для вертикального направления: число видимых рядов считается по высоте контейнера, perPage перезаписывается при пересчёте. Для горизонтального направления задаёт только высоту слайда.

Для вертикального направления задайте высоту viewport в CSS, чтобы слайдер мог рассчитать число видимых рядов.

Фиксированная ширина слайда (px или CSS, например '12rem', '30%'). Для горизонтального направления: число видимых слайдов считается по ширине контейнера, опция perPage перезаписывается при каждом пересчёте и не задаёт ширину слайда. Для вертикального направления задаёт только ширину слайда (высота — как без этой опции).

const slider = new Tvist('.slider', { fixedWidth: '12rem', gap: 16 })

Пример фиксированных размеров.

Максимальное количество слайдов для короткого flick в обычном режиме. Длинное перетаскивание может пройти больше слайдов.

Сила инерции (flick power). Множитель скорости при расчёте дистанции momentum scroll и snap после drag в обычном режиме (drag: true)

CSS селектор для элементов, которые должны сохранять фокус при перетаскивании

Привязка к слайдам в free режиме. Если true, после momentum scroll будет snap к ближайшему слайду

Расстояние между слайдами: число (px) или CSS-строка (например '1rem', '12px'). Строковые значения измеряются в DOM относительно трека слайдера.

Сетка слайдов

const slider = new Tvist('.slider', {
  grid: { rows: 2, cols: 3, gap: { row: 12, col: 16 } },
})

Размеры dimensions задаются парами [colSpan, rowSpan]. Примеры сетки.

Вложенные настройки →

Удержание для сценариев историй:

• false / undefined — выключено (по умолчанию)
• true — включено с дефолтными настройками
• HoldToPauseOptions — полный контроль

Удержание приостанавливает autoplay и при настройке video.pauseOnHold — видео. Помимо событий экземпляра на слайде отправляются DOM-события из TVIST_DOM_EVENTS с detail: { index, pointerType }, без всплытия.

Пример историй.

Вложенные настройки →

Если true, слайдер будет вести себя как навигация (клики по слайдам делают их активными). Используется для создания thumbnail-слайдеров

Настройки управления с клавиатуры; в текущей версии обработчики не реализованы.

Вложенные настройки →

Ленивая загрузка изображений

Используйте data-src и data-srcset, чтобы загрузкой управлял модуль. Для стандартного loading="lazy" используйте nativeLazyAdjacent.

Пример lazy loading.

Вложенные настройки →

Бесконечная прокрутка. ‘auto’ - определяется автоматически на основе количества слайдов.

Поддерживаются следующие варианты:

• false — выключено (по умолчанию)
• true — включено (эквивалентно { enabled: true, withClones: false })
• 'auto' — режим автоопределения (как и раньше)
• LoopOptions — объект с расширенной конфигурацией

В обычном loop слайды переставляются в DOM. При withClones: true создаются клоны; для логического индекса используйте realIndex, для числа оригиналов — originalSlideCount.

const slider = new Tvist('.slider', {
  loop: { enabled: true, withClones: true },
})

Варианты loop.

Вложенные настройки →

Режим бегущей строки (непрерывная прокрутка)

Автоматически включает loop. При объектной форме пауза при наведении включается явно.

const slider = new Tvist('.slider', {
  marquee: { speed: 50, direction: 'left', pauseOnHover: true },
})

Пример бегущей строки.

Вложенные настройки →

Предзагрузка изображений с нативным loading="lazy" у соседних слайдов и/или целевого при переходе. Полезно для effect: 'cube', когда соседняя грань видна до подгрузки браузером. true — по умолчанию только при начале перехода; соседи при init — onInit: true.

В отличие от lazy, работает с обычными <img src="…" loading="lazy">: переводит подходящие изображения в eager. Это помогает избежать пустой соседней грани во время cube-перехода.

Для ручной подгрузки экспортируется утилита forceEagerLoadingForLazyImages: import { forceEagerLoadingForLazyImages } from 'tvist'. Она переводит изображения с loading="lazy" внутри переданного элемента в eager.

Вложенные настройки →

Минимальный интервал (мс) между вызовами next()/prev(). В loop повторные шаги в том же направлении игнорируются до завершения перехода. Полезно при speed: 0 или при серии программных вызовов.

Обработчики событий слайдера

const slider = new Tvist('.slider', {
  on: { slideChangeEnd: index => console.log(index) },
})

Имена событий и аргументы перечислены в таблице событий.

Пагинация. true — буллеты в стандартном контейнере внутри root (создаётся, если отсутствует), объект — кастомная настройка. Созданный контейнер удаляется при отключении опции или destroy().

Внешний контейнер можно передать селектором или элементом.

const slider = new Tvist('.slider', {
  pagination: { type: 'bullets', limit: 5, strategy: 'even' },
})

Все варианты пагинации.

Вложенные настройки →

Peek — отступы, показывающие часть соседних слайдов (чтобы было видно, что есть ещё слайды). Для горизонтального слайдера: left/right, для вертикального: top/bottom.

peek: 10
peek: '1rem'
peek: { left: 10, right: 20 }
peek: { top: 10, bottom: 20 }

Числа задаются в пикселях, строки — в CSS-единицах. Для горизонтального слайдера используйте left/right, для вертикального — top/bottom.

Живые примеры peek.

Вложенные настройки →

Peek trim: при true (по умолчанию) концовка прижимается к краю — последний слайд без дыры справа/снизу. При включённом loop не применяется.

Количество слайдов на странице (видимых одновременно).

При autoWidth, autoHeight, fixedWidth или fixedHeight количество видимых слайдов определяется геометрией. Не задавайте дробное значение для сетки.

const slider = new Tvist('.slider', { perPage: 3, gap: 20 })

Предотвращать клики по слайдам во время перетаскивания

Предотвращать распространение событий клика во время анимации

Автоматически возвращаться к первому слайду после достижения последнего (работает без loop) Применяется к навигации, autoplay и другим способам перехода между слайдами

Используется без loop. Для возврата перетаскиванием дополнительно включите rewindByDrag.

Разрешить перемотку карусели перетаскиванием, если включён rewind.

Округлять translate и размеры до целых пикселей при применении в DOM. Помогает убрать субпиксельные щели/мыло на некоторых DPR и браузерах. Аналогично roundLengths в Swiper.

Эффект “резинки” при перетаскивании за границы

Кастомный скроллбар для навигации

Вложенные настройки →

Минимальный размер слайда (ширина или высота) для автоматического расчета perPage

Количество слайдов, пролистываемых за один раз.

Задаёт шаг next() и prev(). Прямой переход scrollTo(index) использует указанный индекс.

Скорость анимации перехода в миллисекундах

Индекс начального слайда

Синхронизировать ли слайдеры при перетаскивании (drag). Если false, то при перетаскивании одного слайдера другой не будет переключаться, синхронизация сработает только при клике или переключении стрелками.

Связь с thumbnail-слайдером

Вложенные настройки →

Управление видео внутри слайдов (HTML <video> и iframe YouTube/Vimeo).

• false — выключено (по умолчанию)
• true — включено с дефолтными настройками
• VideoOptions — полный контроль

Поддерживаются HTML <video> и iframe YouTube/Vimeo. Автовоспроизведение зависит от политики браузера; для HTML-video обычно нужен выключенный звук.

const slider = new Tvist('.slider', {
  video: { autoplay: true, muted: true },
  autoplay: { waitForVideo: true },
})

Примеры видео.

Вложенные настройки →

Отслеживание видимости слайдера для приостановки autoplay/marquee.

• false — выключено
• true — включено с дефолтными настройками (по умолчанию)
• VisibilityOptions — полный контроль

Вложенные настройки →

Управление колёсиком мыши

Вложенные настройки →

Следующий слайд (или страница при perPage > 1)

if (slider.canScrollNext) slider.next()

Предыдущий слайд (или страница при perPage > 1)

if (slider.canScrollPrev) slider.prev()

Переход к слайду по индексу

Индекс логический (realIndex), начиная с нуля. instant: true отключает анимацию перехода.

slider.scrollTo(2)
slider.scrollTo(0, true)

Обновить размеры и пересчитать позиции

Вызывайте после изменения содержимого или DOM-структуры слайдов. Изменение размеров контейнера отслеживается автоматически.

slider.container.appendChild(newSlide)
slider.update()

Обновить опции слайдера динамически (без пересоздания)

Передавайте только изменённые параметры. Вложенный объект опции заменяется целиком; для сохранения его полей передайте их снова. Исключение — поля browserFixes, которые объединяются с текущими. После обновления вызывается optionsUpdated.

slider.updateOptions({ perPage: 4, gap: 30 })
slider.updateOptions({ autoplay: { delay: 5000, pauseOnHover: true } })

Живой пример обновления опций.

Отключить слайдер (превратить в статичный контент) Убирает transform, отключает модули, но сохраняет экземпляр

slider.disable()

Включить слайдер (восстановить функциональность)

slider.enable()

Уничтожить экземпляр и очистить ресурсы. Вложенные Tvist по умолчанию не уничтожаются — задайте { destroyNested: true }, если нужно снести всё поддерево. Повторный вызов безопасен (no-op).

Отписывается от событий, уничтожает модули и очищает созданные элементы управления. По умолчанию вложенные слайдеры продолжают работать.

slider.destroy({ destroyNested: true })

Подписаться на событие

const handler = index => console.log(index)
slider.on('slideChangeEnd', handler)

При поздней подписке некоторые события инициализации воспроизводят последние аргументы: created, refresh, setTranslate, progress, navigation:mounted, pagination:mounted, breakpoint. Для lock/unlock воспроизводится текущее состояние.

Отписаться от события

Без второго аргумента снимает все обработчики указанного события.

slider.off('slideChangeEnd', handler)
slider.off('slideChangeEnd')

Вызвать событие

slider.emit('customEvent', { source: 'button' })

Подписаться на событие один раз

slider.once('slideChangeEnd', index => console.log(index))

Если для события доступно сохранённое состояние инициализации, обработчик выполняется сразу один раз.

Синхронизация с другим экземпляром Tvist

Для двусторонней связи вызовите метод на обоих экземплярах. Настройка syncOnDrag управляет синхронизацией при перетаскивании.

main.sync(thumbs)
thumbs.sync(main)

Уникальный идентификатор экземпляра.

Корневой элемент слайдера.

На root выставляются классы из Tvist.CLASSES:

slider.root.classList.contains(Tvist.CLASSES.locked)

Элемент viewport, обрезающий видимую область.

Контейнер слайдов, к которому применяется transform.

Текущая конфигурация. Для изменения используйте updateOptions().

Ссылка только для чтения; для изменения конфигурации используйте updateOptions().

Проверить, включен ли слайдер

Получить список слайдов

Порядок соответствует текущему DOM; loop может его менять. Для стилей определённого слайда используйте data-tvist-slide-index, а не :nth-child().

Количество оригинальных слайдов (без клонов). В режиме loop.withClones не учитывает клонированные слайды по краям.

Общее количество слайдов в DOM (включая клоны). В режиме loop.withClones включает клонированные слайды по краям. Совпадает с originalSlideCount если loop.withClones не используется.

Получить текущий индекс активного слайда

Индекс в текущем DOM. Для логического индекса исходного слайда при loop используйте realIndex.

Получить текущий логический индекс слайда (с учётом loop)

slider.on('slideChangeEnd', () => console.log(slider.realIndex))

Проверить, можно ли листать вперёд

Проверить, можно ли листать назад

Получить публичное API autoplay модуля

Доступно при активном модуле autoplay. Методы управления.

Получить публичное API video модуля

Доступно при активном модуле video. Методы управления.

Continuous motion controls, when enabled.

slider.marquee возвращает управление непрерывной прокруткой: start/stop, pause/resume, проверки состояния, setSpeed/getSpeed и setDirection/getDirection. Если marquee отключён, возвращается undefined.

Explicit lazy image loading, when enabled.

slider.lazyload?.loadSlide(2) загружает изображения выбранного слайда, slider.lazyload?.loadAll() — всех слайдов. Если lazy отключён, возвращается undefined.

Visibility controls, when enabled.

slider.visibility?.isVisible() возвращает состояние видимости; slider.visibility?.check() принудительно проверяет видимость. При отключённой опции возвращается undefined.

Matching breakpoint, or null when no breakpoint applies.

Номер активного брейкпоинта либо null, если совпадений нет.

Ссылка на экземпляр Tvist на корневом DOM-элементе.

Позволяет получить экземпляр через DOM. После destroy() ссылка очищается; повторное создание на том же root корректно заменяет экземпляр.

const element = document.querySelector('.slider')
element?.tvistInstance?.next()

После создания слайдера

К этому моменту на root уже установлен Tvist.CLASSES.created.

slider.on('created', tvist => console.log(tvist.slides.length))

Перед уничтожением

Вызывается до очистки модулей и DOM, перед добавлением класса destroyed.

При уничтожении

К этому моменту на root установлен Tvist.CLASSES.destroyed.

Клик по слайду

Вызван update() — пересчитаны размеры/позиции

Завершилось изменение размера контейнера

Перед сменой слайда

Начало смены слайда (старт анимации)

data?.isDrag показывает, связан ли переход с drag. При loop индекс события учитывает логический исходный слайд.

Смена слайда завершена (после анимации)

slider.on('slideChangeEnd', index => {
  counter.textContent = String(index + 1)
})

Перед началом анимации перехода (для loop fix)

Начало анимации перехода

Конец анимации перехода

Слайд вошёл в видимую область (по расчёту движка: пересечение с viewport; для effect cube — та же геометрия граней, что и у эффекта куба). За одну анимацию или кадр событие может прийти для нескольких слайдов (например perPage>1 или при кубе — до двух граней, пока идёт переход). Для логики «текущий слайд» используйте slideChangeEnd / activeIndex, а не этот колбэк. В обработчике опирайтесь на аргумент index, а не на activeIndex в момент вызова.

Во время одного перехода событие может прийти для нескольких слайдов. Ориентируйтесь на аргумент index; для текущего активного слайда используйте slideChangeEnd.

Слайд вышел из видимой области (см. замечания к visible)

Во время прокрутки (тики анимации / драг)

Прогресс прокрутки 0…1, только при !loop

Вызывается только без loop; значение в диапазоне 0…1.

Достигнут первый слайд

Достигнут последний слайд

Начало перетаскивания

Во время перетаскивания

Конец перетаскивания

Смена breakpoint

Слайдер заблокирован (контент помещается в область)

Слайдер разблокирован

Обновлены опции через updateOptions()

slider.on('optionsUpdated', (tvist, newOptions) => console.log(newOptions))

Видео загрузило метаданные и готово к воспроизведению

Видео начало воспроизведение

Видео поставлено на паузу

Видео завершило воспроизведение

Прогресс воспроизведения видео (0…1)

Прогресс активного сегмента (текущий слайд, 0…1)

segmentIndex и segmentProgress описывают активный сегмент; totalSegments — общее количество. Подходит для прогресса историй.

Начало long press удержания

Требуется включённый holdToPause. На слайде также отправляется DOM CustomEvent из TVIST_DOM_EVENTS без всплытия.

Конец long press удержания

Отправляется при завершении или отмене удержания, включая начало drag.

Слайдер стал видимым

Слайдер скрыт

После вызова enable() и восстановления работы слайдера.

После вызова disable() и перехода к статичному контенту.

Автопрокрутка запущена.

Автопрокрутка остановлена.

Автопрокрутка поставлена на паузу.

Автопрокрутка продолжена после паузы.

Бегущая строка запущена.

Бегущая строка остановлена.

Бегущая строка поставлена на паузу.

Бегущая строка продолжена после паузы.

Кнопки навигации смонтированы.

Пагинация смонтирована.

Пользователь выбрал слайд в слайдере-миниатюрах.

Перед применением transform к контейнеру. Используется собственными эффектами.

Перед перестановкой слайдов для коррекции loop. Событие для расширений.

После коррекции loop. Событие для расширений.

Изображение с data-src успешно загружено модулем LazyLoad.

slider.on('lazyLoaded', (img, slideIndex) => {
  img.classList.add('loaded')
})

Загрузка изображения модулем LazyLoad завершилась ошибкой. Можно показать запасное изображение.

Library version.

BEM class names.

Устарело: Use Tvist.CLASSES.block.