Modules

模組

Complete reference for every DriftSlider module — options, APIs, and usage examples.

每個 DriftSlider 模組的完整參考 — 選項、API 和使用範例。

Overview

概覽

DriftSlider uses a modular architecture. Import only what you need to keep your bundle size small. Each module extends the slider with additional functionality — from navigation controls to advanced visual effects.

DriftSlider 使用模組化架構。只匯入你需要的模組以保持打包體積精簡。每個模組為滑塊擴展額外功能 — 從導航控制到進階視覺效果。

Register modules via the modules array when creating a new instance:

建立新實例時,透過 modules 陣列註冊模組:

js
import DriftSlider from 'drift-slider';
import { Navigation, Pagination } from 'drift-slider/modules';

new DriftSlider('.slider', {
  modules: [Navigation, Pagination],
  navigation: true,
  pagination: { el: '.pagination', type: 'bullets' }
});

When using the UMD / CDN build, all modules are available on the global DriftSlider object:

使用 UMD / CDN 版本時,所有模組都可從全域 DriftSlider 物件取得:

js
const { Navigation, Pagination } = DriftSlider;

new DriftSlider('.slider', {
  modules: [Navigation, Pagination],
  navigation: true,
  pagination: { el: '.pagination' }
});

Pagination

分頁

Renders pagination indicators — bullets, fraction counters, or a progress bar — to show the current position within the slider.

渲染分頁指示器 — 圓點、分數計數器或進度條 — 顯示滑塊中的目前位置。

Import

js
// ESM
import { Pagination } from 'drift-slider/modules';

// UMD
const { Pagination } = DriftSlider;

Options

ParameterTypeDefaultDescription
elstring | HTMLElement | nullnullPagination container selector or element
type'bullets' | 'fraction' | 'progressbar''bullets'Pagination display type
clickablebooleantrueAllow clicking bullets to navigate
bulletClassstring'drift-pagination__bullet'Class for each bullet element
bulletActiveClassstring'drift-pagination__bullet--active'Class for the active bullet
currentClassstring'drift-pagination__current'Class for the current number in fraction mode
totalClassstring'drift-pagination__total'Class for the total number in fraction mode
progressClassstring'drift-pagination__progress'Class for the progress bar fill
renderBullet(index, className) => stringnullCustom render function for bullets
renderFraction(currentClass, totalClass) => stringnullCustom render function for fraction
renderProgressbar(progressClass) => stringnullCustom render function for progress bar
stylePartial<CSSStyleDeclaration> | nullnullInline styles for the pagination container
bulletStylePartial<CSSStyleDeclaration> | nullnullInline styles for each bullet
bulletActiveStylePartial<CSSStyleDeclaration> | nullnullInline styles for the active bullet
progressStylePartial<CSSStyleDeclaration> | nullnullInline styles for the progress bar fill

Instance API

Method / PropertyDescription
slider.pagination.update()Recalculate and refresh pagination state
slider.pagination.render()Re-render the pagination DOM
slider.pagination.elReference to the pagination container element

Example

js
new DriftSlider('.slider', {
  modules: [Pagination],
  pagination: {
    el: '.slider-pagination',
    type: 'bullets',
    clickable: true,
    renderBullet(index, className) {
      return `<span class="${className}">${index + 1}</span>`;
    }
  }
});

Autoplay

自動播放

Automatically advances slides at a configurable interval. Supports pausing on hover and stopping on user interaction.

以可配置的間隔自動推進投影片。支援懸停暫停和使用者互動時停止。

Import

js
// ESM
import { Autoplay } from 'drift-slider/modules';

// UMD
const { Autoplay } = DriftSlider;

Options

ParameterTypeDefaultDescription
enabledbooleanfalseEnable autoplay on init
delaynumber3000Delay between slide transitions in milliseconds
disableOnInteractionbooleantrueStop autoplay when the user interacts with the slider
pauseOnMouseEnterbooleanfalsePause autoplay when the cursor enters the slider
stopOnLastSlidebooleanfalseStop at the last slide instead of looping (non-loop mode)
reverseDirectionbooleanfalseAutoplay in reverse (previous instead of next)

Instance API

MethodDescription
slider.autoplay.start()Start autoplay
slider.autoplay.stop()Stop autoplay completely
slider.autoplay.pause()Temporarily pause autoplay
slider.autoplay.resume()Resume after a pause
slider.autoplay.running()Returns true if autoplay is currently running

Events

EventDescription
autoplayStartFired when autoplay starts
autoplayStopFired when autoplay stops
autoplayPauseFired when autoplay is paused
autoplayResumeFired when autoplay resumes

Example

js
const slider = new DriftSlider('.slider', {
  modules: [Autoplay],
  autoplay: {
    enabled: true,
    delay: 5000,
    pauseOnMouseEnter: true,
    disableOnInteraction: false
  }
});

slider.on('autoplayPause', () => {
  console.log('Autoplay paused');
});

// Programmatic control
slider.autoplay.stop();
slider.autoplay.start();

EffectFade

淡入淡出效果

Replaces the default slide transition with a fade effect. Slides cross-fade in place rather than sliding horizontally.

用淡入淡出效果取代預設的滑動轉場。投影片原地交叉淡入淡出,而非水平滑動。

Import

js
// ESM
import { EffectFade } from 'drift-slider/modules';

// UMD
const { EffectFade } = DriftSlider;

Options

ParameterTypeDefaultDescription
crossFadebooleanfalseEnable cross-fade so the incoming slide fades in while the outgoing slide fades out simultaneously

Note: Requires effect: 'fade' in the main slider options.

Example

js
new DriftSlider('.slider', {
  modules: [EffectFade],
  effect: 'fade',
  fadeEffect: {
    crossFade: true
  }
});

EffectCoverflow

封面流效果

Creates a 3D coverflow effect inspired by album art browsers. Side slides rotate, scale, and recede in depth around the active center slide.

建立受專輯封面瀏覽器啟發的 3D 封面流效果。側邊投影片圍繞活動中心投影片旋轉、縮放和後退。

Import

js
// ESM
import { EffectCoverflow } from 'drift-slider/modules';

// UMD
const { EffectCoverflow } = DriftSlider;

Options

ParameterTypeDefaultDescription
depthnumber2003D depth offset in pixels (translateZ)
rotatenumber30Rotation angle in degrees for side slides
scalenumber0.85Scale factor for side slides
stretchnumber0Stretch offset between slides in pixels
modifiernumber1Multiplier applied to all effect values
overlaybooleantrueShow a darkening overlay on side slides
overlayColorstring'rgba(0,0,0,0.4)'Color of the overlay
opacitynumber0.6Opacity of side slides
activeOpacitynumber1Opacity of the active slide
align'center' | 'bottom' | 'top''center'Vertical alignment of slides
fillCenterbooleanfalseStretch the active slide to fill the center area
cropSidesbooleanfalseCrop side slides at the container edge
staggerYnumber0Vertical stagger offset in pixels
visibleSides'both' | 'prev' | 'next''both'Which side slides are visible

Note: Requires effect: 'coverflow' in the main slider options. Typically used with centeredSlides: true and slidesPerView: 3.

Example

js
new DriftSlider('.slider', {
  modules: [EffectCoverflow],
  effect: 'coverflow',
  centeredSlides: true,
  slidesPerView: 3,
  coverflowEffect: {
    depth: 250,
    rotate: 45,
    scale: 0.8,
    overlay: true,
    overlayColor: 'rgba(0,0,0,0.5)'
  }
});

EffectCards

卡片效果

Displays slides as stacked cards with support for three distinct modes: stack, diagonal, and flip. Cards can be swiped away to reveal the next one.

將投影片顯示為堆疊卡片,支援三種不同模式:stackdiagonalflip。可滑動卡片以顯示下一張。

Import

js
// ESM
import { EffectCards } from 'drift-slider/modules';

// UMD
const { EffectCards } = DriftSlider;

Options

ParameterTypeDefaultDescription
mode'stack' | 'diagonal' | 'flip''stack'Card effect mode
direction'tl-br' | 'bl-tr' | 'tr-bl' | 'br-tl' | 'auto''tl-br'Direction of the card stack offset
offsetXnumber30Horizontal offset between stacked cards in pixels
offsetYnumber30Vertical offset between stacked cards in pixels
scalenumber0.92Scale factor for stacked cards behind the active card
opacitynumber0.85Opacity of stacked cards behind the active card
diagonalMultipliernumber2.5Offset multiplier used in diagonal mode
flipAxis'Y' | 'X''Y'Rotation axis used in flip mode
overlaybooleantrueShow a darkening overlay on stacked cards
overlayColorstring'rgba(0,0,0,0.15)'Overlay color
shadowbooleantrueShow drop shadows on cards
shadowColorstring'rgba(0,0,0,0.25)'Shadow color
shadowBlurnumber20Shadow blur radius in pixels

Note: Requires effect: 'cards' in the main slider options.

Example

js
new DriftSlider('.slider', {
  modules: [EffectCards],
  effect: 'cards',
  cardsEffect: {
    mode: 'stack',
    direction: 'tl-br',
    offsetX: 20,
    offsetY: 20,
    scale: 0.9,
    shadow: true,
    shadowBlur: 30
  }
});

Keyboard

鍵盤

Enables keyboard arrow-key navigation for the slider. By default, the slider only responds to key events when it is visible in the viewport.

啟用滑塊的鍵盤方向鍵導航。預設情況下,滑塊僅在可見於視窗時回應鍵盤事件。

Import

js
// ESM
import { Keyboard } from 'drift-slider/modules';

// UMD
const { Keyboard } = DriftSlider;

Options

ParameterTypeDefaultDescription
enabledbooleanfalseEnable keyboard navigation
onlyInViewportbooleantrueOnly respond to key events when the slider is in the viewport

Instance API

MethodDescription
slider.keyboard.enable()Enable keyboard control at runtime
slider.keyboard.disable()Disable keyboard control at runtime

Example

js
new DriftSlider('.slider', {
  modules: [Keyboard],
  keyboard: {
    enabled: true,
    onlyInViewport: true
  }
});

A11y

無障礙

Enhances the slider with ARIA attributes, roles, and live-region announcements so assistive technologies can convey slide content and navigation to users.

透過 ARIA 屬性、角色和即時區域通知增強滑塊,讓輔助技術能向使用者傳達投影片內容和導航資訊。

Import

js
// ESM
import { A11y } from 'drift-slider/modules';

// UMD
const { A11y } = DriftSlider;

Options

ParameterTypeDefaultDescription
enabledbooleantrueEnable accessibility features
prevSlideMessagestring'Previous slide'aria-label for the previous button
nextSlideMessagestring'Next slide'aria-label for the next button
firstSlideMessagestring'This is the first slide'Announced when the first slide is reached
lastSlideMessagestring'This is the last slide'Announced when the last slide is reached
paginationBulletMessagestring'Go to slide {{index}}'aria-label template for pagination bullets
containerMessagestring | nullnullaria-label for the slider container
containerRoleDescriptionstring'carousel'aria-roledescription for the container
slideRolestring'group'ARIA role assigned to each slide
slideRoleDescriptionstring'slide'aria-roledescription for each slide
liveRegionbooleantrueCreate an aria-live region that announces slide changes

Example

js
new DriftSlider('.slider', {
  modules: [Navigation, Pagination, A11y],
  navigation: true,
  pagination: { el: '.pagination' },
  a11y: {
    enabled: true,
    containerMessage: 'Featured products carousel',
    prevSlideMessage: 'Go to previous product',
    nextSlideMessage: 'Go to next product',
    paginationBulletMessage: 'Go to product {{index}}'
  }
});

ScrollAos

滾動動畫

Integrates with the AOS (Animate On Scroll) library to trigger entrance animations when the slider scrolls into view. Individual slides can animate with staggered delays.

整合 AOS (Animate On Scroll) 函式庫,在滑塊滾動進入視窗時觸發進場動畫。個別投影片可以交錯延遲動畫。

Import

js
// ESM
import { ScrollAos } from 'drift-slider/modules';

// UMD
const { ScrollAos } = DriftSlider;

Options

ParameterTypeDefaultDescription
enabledbooleanfalseEnable scroll-triggered animations
animationstring'fade-up'AOS animation class applied to the container
durationnumber800Animation duration in milliseconds
offsetnumber120Scroll offset (in pixels) before the animation triggers
oncebooleantrueOnly animate the first time the element scrolls into view
setContainerAosbooleantrueAutomatically set data-aos attribute on the slider container
slideAnimationstring | nullnullAOS animation class applied individually to each slide
slideDelaynumber100Stagger delay between each slide animation in milliseconds
refreshOnChangebooleanfalseCall AOS.refresh() on every slide change

Note: This module requires the external AOS library to be loaded on the page.

Example

js
// Make sure AOS is loaded and initialized
import AOS from 'aos';
import 'aos/dist/aos.css';
AOS.init();

new DriftSlider('.slider', {
  modules: [ScrollAos],
  scrollAos: {
    enabled: true,
    animation: 'fade-up',
    duration: 1000,
    slideAnimation: 'fade-right',
    slideDelay: 150
  }
});