Опции слайдера

Полный справочник всех доступных опций для настройки Tvist слайдера.

Опция	Тип	По умолчанию	Описание
`perPage`	`number`	`1`	Количество слайдов на странице (видимых одновременно).
`slidesPerGroup`	`number`	`1`	Количество слайдов, пролистываемых за один раз.
`autoWidth`	`boolean`	`false`	Если true, ширина слайдов определяется их содержимым (не задаётся слайдером). Рекомендуется perPage: 1.
`autoHeight`	`boolean`	`false`	Если true, высота слайдов определяется их содержимым (для вертикального направления). Рекомендуется perPage: 1.
`fixedWidth`	`number \| string`	`undefined`	Фиксированная ширина слайда (px или CSS, например `'12rem'`, `'30%'`). Для горизонтального направления: число видимых слайдов считается по ширине контейнера, опция `perPage` перезаписывается при каждом пересчёте и не задаёт ширину слайда. Для вертикального направления задаёт только ширину слайда (высота — как без этой опции).
`fixedHeight`	`number \| string`	`undefined`	Фиксированная высота слайда (px или CSS). Для вертикального направления: число видимых рядов считается по высоте контейнера, `perPage` перезаписывается при пересчёте. Для горизонтального направления задаёт только высоту слайда.
`slideMinSize`	`number`	`undefined`	Минимальный размер слайда (ширина или высота) для автоматического расчета perPage
`gap`	`number \| string`	`0`	Расстояние между слайдами: число (px) или CSS-строка (например `'1rem'`, `'12px'`). Строковые значения измеряются в DOM относительно трека слайдера.
`roundLengths`	`boolean`	`true`	Округлять translate и размеры до целых пикселей при применении в DOM. Помогает убрать субпиксельные щели/мыло на некоторых DPR и браузерах. Аналогично `roundLengths` в Swiper.
`peek`	`number \| string`	`undefined`	Peek — отступы, показывающие часть соседних слайдов (чтобы было видно, что есть ещё слайды). Для горизонтального слайдера: left/right, для вертикального: top/bottom. peek: 10 peek: '1rem' peek: { left: 10, right: 20 } peek: { top: 10, bottom: 20 }
`peekTrim`	`boolean`	`true`	Peek trim: при true (по умолчанию) концовка прижимается к краю — последний слайд без дыры справа/снизу. При включённом loop не применяется.
`speed`	`number`	`300`	Скорость анимации перехода в миллисекундах
`navThrottleMs`	`number`	`0`	Минимальный интервал (мс) между вызовами next()/prev() при отсутствии анимации перехода. Пока идёт анимация (animator), повторные вызовы всё равно игнорируются. Полезно при speed: 0 или при серии программных вызовов.
`direction`	`'horizontal' \| 'vertical'`	`'horizontal'`	Направление прокрутки слайдера
`center`	`boolean \| CenterOptions`	`false`	Центрирование слайдов. - `true` — центрирует активный слайд в viewport (режим "active"). - Объект `{ active?, focus?, justify? }` — тонкая настройка: - `active: true` — центрирует активный слайд всегда, включая края (аналог `center: true`) - `focus: true` — центрирует активный слайд, когда возможно; у краёв без пустот (как Splide focus:center) - `justify: true` — визуально центрирует все слайды когда locked (как `justify-content: center`)
`debug`	`boolean`	`false`	Режим отладки: вывод предупреждений в консоль (arrows not found, container not found и т.д.)
`start`	`number`	`0`	Индекс начального слайда
`drag`	`boolean \| 'free'`	`true`	Включить перетаскивание слайдов. 'free' - свободная прокрутка без привязки к слайдам
`dragSpeed`	`number`	`1`	Множитель скорости перетаскивания
`rubberband`	`boolean`	`true`	Эффект "резинки" при перетаскивании за границы
`freeSnap`	`boolean`	`false`	Привязка к слайдам в free режиме. Если true, после momentum scroll будет snap к ближайшему слайду
`flickPower`	`number`	`600`	Сила инерции (flick power). Множитель скорости при расчёте дистанции momentum scroll и snap после drag в обычном режиме (`drag: true`)
`flickMaxPages`	`number`	`1`	Максимальное количество страниц (viewport) для flick в обычном режиме
`focusableElements`	`string`	`'button, a, input, select, textarea'`	CSS селектор для элементов, которые должны сохранять фокус при перетаскивании
`preventClicks`	`boolean`	`true`	Предотвращать клики по слайдам во время перетаскивания
`preventClicksPropagation`	`boolean`	`true`	Предотвращать распространение событий клика во время анимации
`arrows`	`boolean \| boolean`	`false`	Навигационные стрелки. true - автоматическое создание, объект - кастомная настройка
`pagination`	`boolean \| boolean`	`false`	Пагинация. true - автоматическое создание буллетов, объект - кастомная настройка
`autoplay`	`boolean \| number \| AutoplayOptions`	`false`	Автопрокрутка слайдов. - `false` — выключена (по умолчанию) - `true` — включена с задержкой 3000мс и дефолтными настройками - `number` — включена с указанной задержкой в миллисекундах - `AutoplayOptions` — полный контроль: delay, pauseOnHover, pauseOnInteraction, disableOnInteraction, waitForVideo
`video`	`boolean \| VideoOptions`	`false`	Управление видео внутри слайдов (HTML `<video>` и iframe YouTube/Vimeo). - `false` — выключено (по умолчанию) - `true` — включено с дефолтными настройками - `VideoOptions` — полный контроль
`holdToPause`	`boolean \| HoldToPauseOptions`	`undefined`	Удержание для сценариев историй: - `false` / `undefined` — выключено (по умолчанию) - `true` — включено с дефолтными настройками - `HoldToPauseOptions` — полный контроль
`visibility`	`boolean \| VisibilityOptions`	`true`	Отслеживание видимости слайдера для приостановки autoplay/marquee. - `false` — выключено - `true` — включено с дефолтными настройками (по умолчанию) - `VisibilityOptions` — полный контроль
`browserFixes`	`BrowserFixesOptions`	`{ firefoxImageDecoding: true }`	Специфичные фиксы для браузеров
`loop`	`boolean \| 'auto' \| LoopOptions`	`false`	Бесконечная прокрутка. 'auto' - определяется автоматически на основе количества слайдов. Поддерживаются следующие варианты: - `false` — выключено (по умолчанию) - `true` — включено (эквивалентно `{ enabled: true, withClones: false }`) - `'auto'` — режим автоопределения (как и раньше) - `LoopOptions` — объект с расширенной конфигурацией
`rewind`	`boolean`	`false`	Автоматически возвращаться к первому слайду после достижения последнего (работает без loop) Применяется к навигации, autoplay и другим способам перехода между слайдами
`rewindByDrag`	`boolean`	`false`	Разрешить перемотку карусели перетаскиванием, если включён `rewind`.
`lazy`	`boolean \| boolean`	`false`	Ленивая загрузка изображений
`nativeLazyAdjacent`	`boolean \| NativeLazyAdjacentOptions`	`false (выключено)`	Предзагрузка изображений с нативным `loading="lazy"` у соседних слайдов и/или целевого при переходе. Полезно для `effect: 'cube'`, когда соседняя грань видна до подгрузки браузером. `true` — по умолчанию только при начале перехода; соседи при init — `onInit: true`.
`effect`	`'slide' \| 'fade' \| 'cube' \| 'stack'`	`'slide'`	Эффект перехода между слайдами
`fadeEffect`	`object`	`undefined`	Настройки fade эффекта
`stackEffect`	`object`	`undefined`	Настройки stack эффекта
`cubeEffect`	`object`	`undefined`	Настройки cube эффекта
`thumbs`	`object`	`undefined`	Связь с thumbnail-слайдером
`isNavigation`	`boolean`	`false`	Если true, слайдер будет вести себя как навигация (клики по слайдам делают их активными). Используется для создания thumbnail-слайдеров
`grid`	`object`	`undefined`	Сетка слайдов
`marquee`	`boolean \| boolean`	`false`	Режим бегущей строки (непрерывная прокрутка)
`keyboard`	`boolean \| boolean`	`false`	Управление с клавиатуры (стрелки)
`wheel`	`boolean \| boolean`	`false`	Управление колёсиком мыши
`scrollbar`	`boolean \| boolean`	`false`	Кастомный скроллбар для навигации
`breakpoints`	`boolean \| object`	`undefined`	Адаптивные настройки по breakpoints. Ключ - ширина экрана в пикселях
`breakpointsBase`	`'window' \| 'container'`	`'window'`	База для расчёта breakpoints
`enabled`	`boolean`	`true`	Включить/выключить слайдер. При false слайдер не инициализируется (статичный контент)
`syncOnDrag`	`boolean`	`true`	Синхронизировать ли слайдеры при перетаскивании (drag). Если false, то при перетаскивании одного слайдера другой не будет переключаться, синхронизация сработает только при клике или переключении стрелками.
`on`	`object`	`undefined`	Обработчики событий слайдера

Группировка опций

Таблица выше содержит все опции; ниже они сгруппированы по смыслу.

Базовые настройки

perPage — количество видимых слайдов
slidesPerGroup — количество слайдов, пролистываемых за раз (next/prev)
slideMinSize — минимальный размер слайда для авто-расчёта perPage
center — центрирование активного слайда
autoWidth — ширина слайдов по содержимому (горизонтальный слайдер)
autoHeight — высота слайдов по содержимому (вертикальный слайдер)
gap — расстояние между слайдами
peek — отступы, показывающие часть соседних слайдов (число, строка или объект left/right / top/bottom)
peekTrim — прижатие концовки к краю при peek (по умолчанию true; при loop не применяется)
speed — скорость анимации (мс)
direction — направление прокрутки (horizontal | vertical)
start — индекс начального слайда
debug — режим отладки (предупреждения в консоль только при debug: true)

Управление перетаскиванием

drag — включение/отключение перетаскивания (true | false | 'free')
dragSpeed — множитель скорости перетаскивания
rubberband — эффект резинки на краях
freeSnap — snap к слайдам в режиме drag: 'free'
flickPower — сила инерции: множитель скорости для momentum scroll (drag: 'free') и snap после свайпа в обычном режиме (drag: true)
flickMaxPages — максимум viewport-ширин инерции за один flick (ограничивает дальность перелистывания)
focusableElements — CSS-селектор элементов, сохраняющих фокус при перетаскивании
preventClicks — блокировать клики по слайдам во время перетаскивания
preventClicksPropagation — не всплывать клику во время анимации
holdToPause — пауза autoplay (и при необходимости видео) по долгому нажатию: true или объект HoldToPauseOptions с полями threshold (по умолчанию 100 ms), root, exclude, cancelOnDrag. События экземпляра: longPressStart / longPressEnd; на узле слайда дополнительно диспатчатся DOM CustomEvent без всплытия — константы TVIST_DOM_EVENTS, тип TvistLongPressDomEventDetail (см. TypeScript, события)

arrows — стрелки (true или объект с prev, next, disabledClass, hiddenClass, addIcons, hideWhenSinglePage; селекторы/элементы могут быть вне root, см. Примеры навигации)
pagination — пагинация (true или объект с container, type, clickable, bulletClass, bulletActiveClass, renderBullet / renderFraction / renderCustom, hideWhenSinglePage, limit, strategy, remainderStrategy; container может быть вне root)
keyboard — управление с клавиатуры (true или объект с enabled, onlyInViewport)
wheel — управление колёсиком мыши (true или объект с sensitivity, releaseOnEdges)
scrollbar — кастомный скроллбар (true или объект с container, hide, hideDelay, scrollbarClass, trackClass, thumbClass, draggable)

Автоматизация и медиа

autoplay — автопрокрутка (false | true | число мс или объект с delay, pauseOnHover, pauseOnInteraction, disableOnInteraction, waitForVideo)
video — управление видео в слайдах (false | true или объект с autoplay, muted, loop, playsinline, pauseOnLeave, resetOnLeave)
visibility — учёт видимости слайдера в viewport для паузы autoplay/marquee (true по умолчанию или объект с pauseAutoplay, pauseMarquee, threshold)

Режимы отображения

autoWidth / autoHeight — размер слайдов по содержимому
loop — бесконечная прокрутка (true | false | 'auto')
rewind — возврат к первому слайду после последнего (без loop)
effect — эффект перехода (slide | fade | cube | card)
fadeEffect — настройки fade (например crossFade)
cubeEffect — настройки cube (slideShadows, shadow, shadowOffset, shadowScale, perspective, perspectiveOriginY, viewportPadding)
virtual — виртуальные слайды (объект с addSlidesBefore, addSlidesAfter, renderSlide)
grid — сетка (объект с rows, cols, gap, dimensions)
marquee — бегущая строка (true | объект с speed, direction, pauseOnHover)

Дополнительно

enabled — включение/отключение слайдера (при false — статичный контент)
lazy — ленивая загрузка изображений (true или объект с preloadPrevNext)
nativeLazyAdjacent — нативный loading="lazy" на <img>: принудительная подгрузка при переходе и опционально соседей при init (подробнее ниже)
thumbs — связь с слайдером-миниатюрами ({ slider: Tvist })
isNavigation — режим навигации (клики по слайдам переключают слайд)
syncOnDrag — синхронизация при перетаскивании (true по умолчанию). Если false, при перетаскивании (drag) одного слайдера другой не будет переключаться, синхронизация сработает только при клике или переключении стрелками.
breakpoints — адаптивные настройки (ключ — ширина в px, в т.ч. enabled внутри брейкпоинта)
breakpointsBase — база для расчёта breakpoints ('window' | 'container')
on — объект с обработчиками событий (см. События)

`nativeLazyAdjacent` и нативный `loading="lazy"`

Отдельно от модуля LazyLoad (поля data-src / data-srcset) в разметке часто используют обычные <img src="..." loading="lazy">. Браузер откладывает такую загрузку, пока картинка не окажется «рядом» с viewport. При эффекте cube соседняя грань может кратко попасть в кадр до того, как lazy сработает — визуально это пустая грань.

Опция nativeLazyAdjacent (модуль slide-states) для выбранных слайдов выставляет у подходящих изображений loading = 'eager', чтобы загрузка началась заранее.

Значение	Поведение
`false` / не задавать	Выкл.
`true` или `{}`	Только при начале перехода к другому слайду (`beforeSlideChange`): целевой слайд. `onInit` по умолчанию выключен (без лишнего трафика при открытии страницы).
`{ onInit: true }`	Дополнительно после init: prev и next относительно активного (с учётом `loop`).
`{ onTransitionStart: false }`	Отключить подгрузку на переходе (остаётся только явный `onInit`, если задан).

Тип объекта: NativeLazyAdjacentOptions (экспорт из пакета, см. TypeScript). Утилита forceEagerLoadingForLazyImages экспортируется из пакета (import { forceEagerLoadingForLazyImages } from 'tvist').

javascript

// Частый случай: cube + обычные img с loading="lazy"
const slider = new Tvist(root, {
  effect: 'cube',
  nativeLazyAdjacent: true,
})

// Прогреть соседей сразу после монтирования слайдера (больше трафика при загрузке)
const slider2 = new Tvist(root, {
  effect: 'cube',
  nativeLazyAdjacent: { onInit: true, onTransitionStart: true },
})

Примеры использования

Базовая конфигурация

javascript

const slider = new Tvist('.slider', {
  perPage: 3,
  gap: 20,
  speed: 400,
  arrows: true,
  pagination: true
})

С автопрокруткой и loop

javascript

const slider = new Tvist('.slider', {
  perPage: 1,
  autoplay: { delay: 3000, pauseOnHover: true },
  loop: true
})

Drag Free Mode

javascript

// Свободная прокрутка без snap
const slider = new Tvist('.slider', {
  drag: 'free',
  perPage: 3,
  gap: 20
})

// Свободная прокрутка с автоматическим snap
const sliderWithSnap = new Tvist('.slider', {
  drag: 'free',
  freeSnap: true, // Выравнивание к слайду после остановки
  perPage: 3,
  gap: 20
})

Адаптивный слайдер

javascript

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

Сетка на десктопе, слайдер на мобильных

javascript

const slider = new Tvist('.slider', {
  // По умолчанию (десктоп) - отключен
  enabled: false,
  perPage: 1,
  gap: 16,
  drag: true,
  pagination: true,
  
  // На мобильных - включен
  breakpoints: {
    767: {
      enabled: true  // Слайдер активен на экранах ≤767px
    }
  }
})

С эффектами

javascript

const slider = new Tvist('.slider', {
  effect: 'fade',
  fadeEffect: {
    crossFade: true
  },
  speed: 600
})

Полная конфигурация

javascript

const slider = new Tvist('.slider', {
  // Базовые
  perPage: 3,
  gap: 20,
  speed: 400,
  direction: 'horizontal',
  start: 0,
  
  // Управление
  drag: true,
  dragSpeed: 1,
  rubberband: true,
  
  // Навигация
  arrows: true,
  pagination: {
    type: 'bullets',
    clickable: true
  },
  keyboard: true,
  
  // Автоматизация
  autoplay: { delay: 5000, pauseOnHover: true },
  loop: true,
  
  // Адаптивность
  breakpoints: {
    640: { perPage: 1, gap: 10 },
    1024: { perPage: 2, gap: 15 }
  },
  
  // События
  on: {
    slideChangeStart: (index) => {
      console.log('Активный слайд:', index)
    }
  }
})

Приоритет опций

При использовании breakpoints, опции из соответствующего breakpoint переопределяют базовые опции. Например:

javascript

const slider = new Tvist('.slider', {
  perPage: 3,  // Базовое значение
  breakpoints: {
    640: {
      perPage: 1  // На экранах >= 640px будет 1 слайд
    }
  }
})

Динамическое изменение опций

Tvist поддерживает динамическое изменение большинства опций без пересоздания слайдера. Используйте метод updateOptions() для обновления настроек на лету.

Метод updateOptions()

javascript

// Изменить одну опцию
slider.updateOptions({ perPage: 3 })

// Изменить несколько опций
slider.updateOptions({
  perPage: 2,
  gap: 30,
  speed: 500
})

// Цепочка вызовов
slider
  .updateOptions({ perPage: 3 })
  .scrollTo(0)

Поддерживаемые опции

Метод updateOptions() поддерживает изменение следующих опций:

Базовые настройки

perPage - количество слайдов на странице
slideMinSize - минимальный размер слайда
gap - расстояние между слайдами
peek - отступы слайдера
peekTrim - обрезка peek на краях
speed - скорость анимации
direction - направление прокрутки (horizontal / vertical)
center - центрирование активного слайда

Drag

drag - включение/отключение перетаскивания
dragSpeed - скорость перетаскивания
rubberband - эффект резинки
holdToPause - пауза по долгому нажатию (см. опции и события)

Autoplay

autoplay - автопрокрутка (число, true, false или объект с delay, pauseOnHover, pauseOnInteraction, disableOnInteraction, waitForVideo)

События

on - обработчики событий (заменяют предыдущие)

Примеры использования

Адаптация под размер экрана

javascript

const updateSliderForScreen = () => {
  const width = window.innerWidth
  
  if (width < 768) {
    slider.updateOptions({ perPage: 1, gap: 10 })
  } else if (width < 1024) {
    slider.updateOptions({ perPage: 2, gap: 20 })
  } else {
    slider.updateOptions({ perPage: 3, gap: 30 })
  }
}

window.addEventListener('resize', updateSliderForScreen)
updateSliderForScreen()

Переключение направления

javascript

const toggleDirection = () => {
  const current = slider.options.direction
  slider.updateOptions({
    direction: current === 'horizontal' ? 'vertical' : 'horizontal'
  })
}

document.querySelector('.toggle-btn').addEventListener('click', toggleDirection)

Управление автопрокруткой

javascript

// Включить автопрокрутку
slider.updateOptions({ autoplay: 3000 })

// Отключить автопрокрутку
slider.updateOptions({ autoplay: false })

// Изменить скорость
slider.updateOptions({ autoplay: 5000 })

Динамическое изменение gap и peek

javascript

// Изменить отступы
slider.updateOptions({
  gap: 40,
  peek: { left: 20, right: 20 }
})

// Убрать peek
slider.updateOptions({ peek: 0 })

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

javascript

slider.updateOptions({
  on: {
    slideChangeStart: (index) => {
      console.log('Новый обработчик:', index)
      // Новая логика
    }
  }
})

Событие optionsUpdated

При вызове updateOptions() генерируется событие optionsUpdated:

javascript

slider.on('optionsUpdated', (tvist, newOptions) => {
  console.log('Обновлены опции:', newOptions)
  
  // Выполнить дополнительную логику
  if (newOptions.perPage) {
    updatePaginationUI()
  }
})

Пересоздание слайдера (legacy подход)

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

javascript

// Сохраняем текущее состояние
const currentIndex = slider.activeIndex

// Уничтожаем старый экземпляр
slider.destroy()

// Создаём новый с другими опциями
const newSlider = new Tvist('.slider', {
  perPage: 4,
  gap: 30,
  start: currentIndex // Восстанавливаем позицию
})

Ограничения

Некоторые опции не могут быть изменены динамически, так как они влияют на инициализацию модулей:

Регистрация новых модулей требует пересоздания слайдера
Изменение loop может работать некорректно (требуется пересоздание)
Опции, связанные с DOM-структурой модулей

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

Опции слайдера ​

Группировка опций ​

Базовые настройки ​

Управление перетаскиванием ​

Навигация ​

Автоматизация и медиа ​

Режимы отображения ​

Дополнительно ​

nativeLazyAdjacent и нативный loading="lazy" ​

Примеры использования ​

Базовая конфигурация ​

С автопрокруткой и loop ​

Drag Free Mode ​

Адаптивный слайдер ​

Сетка на десктопе, слайдер на мобильных ​

С эффектами ​

Полная конфигурация ​

Приоритет опций ​

Динамическое изменение опций ​

Метод updateOptions() ​

Поддерживаемые опции ​

Базовые настройки ​

Drag ​

Autoplay ​

События ​

Примеры использования ​

Адаптация под размер экрана ​

Переключение направления ​

Управление автопрокруткой ​

Динамическое изменение gap и peek ​

Обновление обработчиков событий ​

Событие optionsUpdated ​

Пересоздание слайдера (legacy подход) ​

Ограничения ​

Опции слайдера

Группировка опций

Базовые настройки

Управление перетаскиванием

Навигация

Автоматизация и медиа

Режимы отображения

Дополнительно

`nativeLazyAdjacent` и нативный `loading="lazy"`

Примеры использования

Базовая конфигурация

С автопрокруткой и loop

Drag Free Mode

Адаптивный слайдер

Сетка на десктопе, слайдер на мобильных

С эффектами

Полная конфигурация

Приоритет опций

Динамическое изменение опций

Метод updateOptions()

Поддерживаемые опции

Базовые настройки

Drag

Autoplay

События

Примеры использования

Адаптация под размер экрана

Переключение направления

Управление автопрокруткой

Динамическое изменение gap и peek

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

Событие optionsUpdated

Пересоздание слайдера (legacy подход)

Ограничения