PixieSlider API Reference
A complete reference for all configuration options, methods, static properties, and module features for PixieSlider and its modules.
Initialization
Create a new slider by passing the container ID or element and an optional configuration object.
import { PixieSlider } from 'pixie-slider';
new PixieSlider('slider-id', {
autoPlay: true,
lazyLoad: true,
captions: true,
// ...other options
});Static Properties
| Property | Type | Default | Description |
|---|---|---|---|
| ALLOW_UNSAFE_HTML | boolean | false | If true, allows raw HTML in slide.html. Warning: This is dangerous! Only enable if you sanitize input yourself. |
| ENABLE_PERF_LOGGING | boolean | false | If true, logs slide load times and frame rates for performance analysis. |
Configuration Options
All options are optional unless otherwise noted. Module-specific options are listed below.
| Option | Type | Default | Description |
|---|---|---|---|
| slides | Slide[] | [] | Array of slide objects. If empty, slides are read from DOM. |
| autoPlay | boolean | true | Enable automatic slide transitions. |
| autoPlaySpeed | number | 4000 | Autoplay interval in ms. |
| pauseOnHover | boolean | false | Pause autoplay on mouse hover. |
| transition | 'slide' | 'fade' | 'slide' | Transition effect between slides. |
| transitionDuration | number | 700 | Transition duration in ms. |
| easing | string | 'ease-in-out' | CSS easing for transitions. |
| spacing | number | 0 | Space (px) between slides. |
| paginationDots | boolean | false | Show pagination dots below the slider. |
| fullscreen | boolean | false | Enable fullscreen button. |
| progressBar | boolean | false | Show a progress bar for autoplay. |
| lazyLoad | boolean | false | Enable lazy loading for images/videos. |
| videoAwareness | boolean | false | Pause autoplay when video is playing. |
| touchSupport | boolean | false | Enable swipe gestures on touch devices. |
| lazyThreshold | number | 2 | How many slides ahead/behind to preload (lazy loading). |
| onSlideChange | (index: number) => void | - | Callback when the slide changes. |
| thumbnails | boolean | false | Show thumbnail navigation. |
| thumbnailSize | number | 60 | Size of thumbnails in px. |
| thumbnailVertical | boolean | false | Display thumbnails vertically. |
| captions | boolean | false | Enable animated captions for slides. |
| captionAnimations | 'fade' | 'slide' | 'zoom' | 'fade' | Default animation for captions. |
| captionPosition | string | 'bottom-center' | Default position for captions. |
| startIndex | number | 0 | Index of the initial slide. |
| navigation | boolean | true | Show next/prev navigation arrows. |
| navPrevTemplate | string | '‹' | HTML for previous arrow button. |
| navNextTemplate | string | '›' | HTML for next arrow button. |
| navPrevClass | string | (see source) | CSS classes for previous arrow. |
| navNextClass | string | (see source) | CSS classes for next arrow. |
| navAutoHide | boolean | false | Auto-hide navigation arrows after inactivity. |
| navAutoHideDelay | number | 2000 | Delay (ms) before auto-hiding navigation arrows. |
| paginationWrapperClass | string | (see source) | CSS classes for pagination wrapper. |
| paginationDotClass | string | (see source) | CSS classes for pagination dots. |
| paginationActiveDotClass | string | (see source) | CSS classes for active pagination dot. |
| paginationDirection | 'horizontal' | 'vertical' | 'horizontal' | Direction of pagination dots. |
| paginationTransitionClass | string | (see source) | CSS classes for pagination transitions. |
| progressBarColor | string | '#000' | Color of the progress bar. |
| touchThreshold | number | 50 | Minimum swipe distance to trigger slide change. |
| touchVerticalTolerance | number | 80 | Vertical movement allowed before canceling swipe. |
| lazyRootMargin | string | '50px' | Root margin for lazy loading (IntersectionObserver). |
| lazyUnload | boolean | false | Unload media when out of view (lazy loading). |
Methods
Call these methods on your PixieSlider instance.
- goToSlide(index: number) — Go to a specific slide.
- nextSlide() — Advance to the next slide.
- prevSlide() — Go to the previous slide.
- pause() — Pause autoplay.
- resume() — Resume autoplay.
- destroy() — Destroy the slider and clean up resources.
- getCurrentSlide() — Get the current slide object.
- getTotalSlides() — Get the total number of slides.
const slider = new PixieSlider('slider-id');
slider.goToSlide(2);
slider.pause();
slider.resume();
slider.destroy();Slide Markup & Data Attributes
Each slide is a
with data-slide and media attributes:
<div data-slide data-media="image.jpg" data-media-alt="Description" data-media-type="image|video" data-captions='{...}' data-duration="4000"></div>- data-media: Image or video URL.
- data-media-type: 'image' or 'video'.
- data-media-alt: Alt text for accessibility.
- data-captions: JSON string for captions (see below).
- data-duration: Per-slide duration (ms).
- data-html: Custom HTML for the slide (see ALLOW_UNSAFE_HTML).
Captions API
Add animated, styled captions to any slide using data-captions:
<div data-slide data-media="image.jpg" data-captions='[
{ "text": "Hello World!", "position": "top-center", "animation": "fade", "delay": 500, "duration": 1000, "className": "text-2xl font-bold" }
]'></div>- text: Caption text.
- position: 'top-left', 'top-center', 'bottom-right', etc.
- animation: 'fade', 'slide-left', 'slide-right', 'slide-top', 'slide-bottom', 'zoom'.
- delay: Animation delay (ms).
- duration: Animation duration (ms).
- className: Extra CSS classes (e.g., Tailwind).
- responsive: true/false for responsive text.
Events & Callbacks
Use these callbacks for integration:
- onSlideChange(index: number): Called when the slide changes.
new PixieSlider('slider-id', {
onSlideChange: (index) => {
console.log('Slide changed to', index);
}
})Module Features & Advanced Options
- Autoplay: Automatic slide transitions, pause/resume, per-slide duration.
- Lazy Loading: Loads images/videos as they approach the viewport for performance. Options: lazyRootMargin, lazyUnload, lazyThreshold.
- Captions: Animated, styled, multi-text captions with full Tailwind support. Options: captionAnimations, captionPosition.
- Fullscreen: Toggle fullscreen mode for immersive viewing.
- Thumbnails: Clickable thumbnail navigation. Options: thumbnailSize, thumbnailVertical.
- Progress Bar: Visual progress indicator for autoplay. Option: progressBarColor.
- Touch Support: Swipe gestures for mobile devices. Options: touchThreshold, touchVerticalTolerance.
- Navigation: Next/prev arrows. Options: navPrevTemplate, navNextTemplate, navPrevClass, navNextClass, navAutoHide, navAutoHideDelay.
- Pagination: Dots navigation. Options: paginationWrapperClass, paginationDotClass, paginationActiveDotClass, paginationDirection, paginationTransitionClass.
- Video Awareness: Pauses autoplay when video is playing.
For more advanced usage and live examples, see the Examples page.