CSS-first slider for the modern web.
A lightweight, performant, and accessible slider library. Built with modern CSS features. Drag, loop, autoplay, and configure with ease. Zero dependencies.
CSS-First
Layout driven by custom properties. Style with standard CSS—no inline styles or JS-driven dimensions.
Lightweight
JS + CSS combined ~6KB minzipped. Ideal for performance-critical projects.
Extensible
Hook into events, sync multiple sliders, or extend with your own navigation and controls.
Event Log
| Event | Data | Time |
|---|
Examples
Multi-Slide View
Show multiple slides at once with gap spacing.
Autoplay + Loop
Auto-advances every 3 seconds with infinite looping. Pauses on hover.
API Reference
createSlider(element, config?)
Creates a new slider instance on the given container element.
import { createSlider } from "aero-slider";
import "aero-slider/slider.css";
const slider = createSlider(document.getElementById("my-slider"), {
loop: true,
pagination: true,
navigation: true,
draggable: true,
});CSS Custom Properties
Layout is controlled via CSS custom properties on the container.
| Property | Default | Description |
|---|---|---|
| --slides-per-view | 1 | Number of visible slides (supports fractional, e.g. 1.5) |
| --slide-gap | 0px | Gap between slides |
| --slide-aspect | 16 / 9 | Aspect ratio for slides |
SliderConfig
All configuration options (all optional with sensible defaults).
| Option | Type | Default | Description |
|---|---|---|---|
| loop | boolean | false | Infinite looping |
| pagination | boolean | true | Show pagination dots |
| navigation | boolean | true | Show prev/next arrows |
| draggable | boolean | true | Enable drag/swipe |
| autoplay | boolean | false | Auto-advance slides |
| autoplayInterval | number | 4000 | Delay between auto-advances (ms) |
SliderInstance
Returned by createSlider().
The instance is also attached to the container element. You can access it via container.aeroSlider when you have a reference to the DOM element.
| Method / Property | Description |
|---|---|
| .next() | Go to next slide |
| .prev() | Go to previous slide |
| .goTo(index) | Jump to a specific slide index |
| .update(config?) | Update config and re-render |
| .destroy() | Tear down and clean up |
| .on(event, cb) | Subscribe to an event |
| .off(event, cb) | Unsubscribe from an event |
| .currentIndex | Current active slide index |
| .slideCount | Total number of slides |
syncThumbnails(primary, thumbnail)
Syncs a primary slider with a thumbnail slider. Returns a teardown function.
import { createSlider, syncThumbnails } from "aero-slider";
const main = createSlider(mainEl, { loop: true });
const thumbs = createSlider(thumbsEl, { pagination: false });
const teardown = syncThumbnails(main, thumbs);
// Later: teardown();Browser Support
Aero Slider relies on modern CSS features to achieve a lightweight, JS-free layout. It degrades gracefully on older browsers, but for the optimal experience, the following minimum versions are recommended:
| CSS Feature | Chrome | Safari | Firefox | Used For |
|---|---|---|---|---|
| CSS Variables | 49+ | 9.1+ | 31+ | Configuring layout and gap size. |
| Scroll Snapping | 69+ | 11+ | 68+ | Locking slides into place after scrolling. |
| aspect-ratio | 88+ | 15+ | 89+ | Maintaining proper height for the slider track. |
| contain: paint | 52+ | 15.4+ | 69+ | Performance optimization for painting slides. |
| overscroll-behavior-x | 63+ | 16+ | 59+ | Preventing rubber-banding when hitting the edge. |