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 陣列註冊模組:
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 物件取得:
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
// ESM
import { Pagination } from 'drift-slider/modules';
// UMD
const { Pagination } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| el | string | HTMLElement | null | null | Pagination container selector or element |
| type | 'bullets' | 'fraction' | 'progressbar' | 'bullets' | Pagination display type |
| clickable | boolean | true | Allow clicking bullets to navigate |
| bulletClass | string | 'drift-pagination__bullet' | Class for each bullet element |
| bulletActiveClass | string | 'drift-pagination__bullet--active' | Class for the active bullet |
| currentClass | string | 'drift-pagination__current' | Class for the current number in fraction mode |
| totalClass | string | 'drift-pagination__total' | Class for the total number in fraction mode |
| progressClass | string | 'drift-pagination__progress' | Class for the progress bar fill |
| renderBullet | (index, className) => string | null | Custom render function for bullets |
| renderFraction | (currentClass, totalClass) => string | null | Custom render function for fraction |
| renderProgressbar | (progressClass) => string | null | Custom render function for progress bar |
| style | Partial<CSSStyleDeclaration> | null | null | Inline styles for the pagination container |
| bulletStyle | Partial<CSSStyleDeclaration> | null | null | Inline styles for each bullet |
| bulletActiveStyle | Partial<CSSStyleDeclaration> | null | null | Inline styles for the active bullet |
| progressStyle | Partial<CSSStyleDeclaration> | null | null | Inline styles for the progress bar fill |
Instance API
| Method / Property | Description |
|---|---|
slider.pagination.update() | Recalculate and refresh pagination state |
slider.pagination.render() | Re-render the pagination DOM |
slider.pagination.el | Reference to the pagination container element |
Example
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
// ESM
import { Autoplay } from 'drift-slider/modules';
// UMD
const { Autoplay } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | Enable autoplay on init |
| delay | number | 3000 | Delay between slide transitions in milliseconds |
| disableOnInteraction | boolean | true | Stop autoplay when the user interacts with the slider |
| pauseOnMouseEnter | boolean | false | Pause autoplay when the cursor enters the slider |
| stopOnLastSlide | boolean | false | Stop at the last slide instead of looping (non-loop mode) |
| reverseDirection | boolean | false | Autoplay in reverse (previous instead of next) |
Instance API
| Method | Description |
|---|---|
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
| Event | Description |
|---|---|
autoplayStart | Fired when autoplay starts |
autoplayStop | Fired when autoplay stops |
autoplayPause | Fired when autoplay is paused |
autoplayResume | Fired when autoplay resumes |
Example
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
// ESM
import { EffectFade } from 'drift-slider/modules';
// UMD
const { EffectFade } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| crossFade | boolean | false | Enable 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
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
// ESM
import { EffectCoverflow } from 'drift-slider/modules';
// UMD
const { EffectCoverflow } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| depth | number | 200 | 3D depth offset in pixels (translateZ) |
| rotate | number | 30 | Rotation angle in degrees for side slides |
| scale | number | 0.85 | Scale factor for side slides |
| stretch | number | 0 | Stretch offset between slides in pixels |
| modifier | number | 1 | Multiplier applied to all effect values |
| overlay | boolean | true | Show a darkening overlay on side slides |
| overlayColor | string | 'rgba(0,0,0,0.4)' | Color of the overlay |
| opacity | number | 0.6 | Opacity of side slides |
| activeOpacity | number | 1 | Opacity of the active slide |
| align | 'center' | 'bottom' | 'top' | 'center' | Vertical alignment of slides |
| fillCenter | boolean | false | Stretch the active slide to fill the center area |
| cropSides | boolean | false | Crop side slides at the container edge |
| staggerY | number | 0 | Vertical 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
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.
將投影片顯示為堆疊卡片,支援三種不同模式:stack、diagonal 和 flip。可滑動卡片以顯示下一張。
Import
// ESM
import { EffectCards } from 'drift-slider/modules';
// UMD
const { EffectCards } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| 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 |
| offsetX | number | 30 | Horizontal offset between stacked cards in pixels |
| offsetY | number | 30 | Vertical offset between stacked cards in pixels |
| scale | number | 0.92 | Scale factor for stacked cards behind the active card |
| opacity | number | 0.85 | Opacity of stacked cards behind the active card |
| diagonalMultiplier | number | 2.5 | Offset multiplier used in diagonal mode |
| flipAxis | 'Y' | 'X' | 'Y' | Rotation axis used in flip mode |
| overlay | boolean | true | Show a darkening overlay on stacked cards |
| overlayColor | string | 'rgba(0,0,0,0.15)' | Overlay color |
| shadow | boolean | true | Show drop shadows on cards |
| shadowColor | string | 'rgba(0,0,0,0.25)' | Shadow color |
| shadowBlur | number | 20 | Shadow blur radius in pixels |
Note: Requires effect: 'cards' in the main slider options.
Example
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
// ESM
import { Keyboard } from 'drift-slider/modules';
// UMD
const { Keyboard } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | Enable keyboard navigation |
| onlyInViewport | boolean | true | Only respond to key events when the slider is in the viewport |
Instance API
| Method | Description |
|---|---|
slider.keyboard.enable() | Enable keyboard control at runtime |
slider.keyboard.disable() | Disable keyboard control at runtime |
Example
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
// ESM
import { A11y } from 'drift-slider/modules';
// UMD
const { A11y } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | Enable accessibility features |
| prevSlideMessage | string | 'Previous slide' | aria-label for the previous button |
| nextSlideMessage | string | 'Next slide' | aria-label for the next button |
| firstSlideMessage | string | 'This is the first slide' | Announced when the first slide is reached |
| lastSlideMessage | string | 'This is the last slide' | Announced when the last slide is reached |
| paginationBulletMessage | string | 'Go to slide {{index}}' | aria-label template for pagination bullets |
| containerMessage | string | null | null | aria-label for the slider container |
| containerRoleDescription | string | 'carousel' | aria-roledescription for the container |
| slideRole | string | 'group' | ARIA role assigned to each slide |
| slideRoleDescription | string | 'slide' | aria-roledescription for each slide |
| liveRegion | boolean | true | Create an aria-live region that announces slide changes |
Example
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
// ESM
import { ScrollAos } from 'drift-slider/modules';
// UMD
const { ScrollAos } = DriftSlider;
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | false | Enable scroll-triggered animations |
| animation | string | 'fade-up' | AOS animation class applied to the container |
| duration | number | 800 | Animation duration in milliseconds |
| offset | number | 120 | Scroll offset (in pixels) before the animation triggers |
| once | boolean | true | Only animate the first time the element scrolls into view |
| setContainerAos | boolean | true | Automatically set data-aos attribute on the slider container |
| slideAnimation | string | null | null | AOS animation class applied individually to each slide |
| slideDelay | number | 100 | Stagger delay between each slide animation in milliseconds |
| refreshOnChange | boolean | false | Call AOS.refresh() on every slide change |
Note: This module requires the external AOS library to be loaded on the page.
Example
// 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
}
});