A self-contained image slider web component — a dependency-free rewrite of the classic FlexSlider 2 image slider as a single custom element.
Drop plain <img> tags inside the element and it becomes a slider. No jQuery, no
stylesheet to load, no icon font, no build step.
<script type="module" src="flex-slider.js"></script>
<flex-slider animation="slide" nav pager autoplay interval="4500" pause-on-hover>
<img src="slide-1.jpg" alt="First slide">
<img src="slide-2.jpg" alt="Second slide">
<img src="slide-3.jpg" alt="Third slide">
</flex-slider>Open demo/flex-slider.html for a live showcase of every
option, or run the test suite by serving the repo and opening
test/index.html.
The element takes every <img> descendant, reads its src and alt, and builds
an inert shadow-DOM track beside the slotted images. The originals stay in the
light DOM as the source of truth but are marked inert and aria-hidden, so they
are never announced twice or reached by the tab key. Each visible slide is a
passive copy — nothing inside the track can steal a click.
All markup and CSS live in the shadow root, so the component cannot leak styles
into the page and page styles cannot reach in. Theming happens through CSS custom
properties and ::part(), both of which cross the shadow boundary on purpose.
The track is measured with offsetLeft / offsetTop rather than assumed from
image widths, so arbitrary image sizes and any container width work without
extra configuration. Adding or removing an image rebuilds the slider
automatically; call refresh() if you change a src in place.
| Attribute | Values | Default | Notes |
|---|---|---|---|
animation |
slide, fade |
slide |
fade stacks slides and cross-fades |
duration |
ms | 700 |
transition duration |
easing |
any CSS timing function | ease |
|
autoplay |
present | off | starts a slideshow |
interval |
ms | 5000 |
time between slides |
pause-on-hover |
present | off | pauses while the pointer is over it |
nav |
present | off | previous/next arrows |
pager |
present | off | dot or thumbnail pager |
thumbs |
present | off | pager renders image thumbnails |
slide-show-at |
index, 0-based | 0 |
slide to start on |
direction |
horizontal, vertical |
horizontal |
axis the track moves along |
reverse |
present | off | animates the other way |
rtl |
present | off | mirrors arrows and layout |
swipe |
on, off |
on | drag or swipe to change slides |
keyboard |
on, off |
on | arrows, Home and End when focused |
smooth-height |
present | off | animates the container height |
height |
any CSS length | auto | fixed box; images crop with object-fit: cover |
theme |
light, dark |
light |
arrow and pager colours |
loop |
on, off |
on |
wraps by default; off stops at the ends |
label |
string | none | accessible name for the region |
prev-label, next-label |
string | "Previous/Next slide" | arrow button labels |
Most booleans are presence-based: nav turns arrows on, leaving it out turns them off. Looping is on by default; use loop="off" to stop at the ends.
const slider = document.querySelector('flex-slider');
slider.next(); // advance one slide
slider.prev(); // go back one slide
slider.goTo(3); // go to index 3
slider.play(); // start the slideshow
slider.pause(); // stop it
slider.refresh(); // re-read the slotted images
slider.reset(); // back to the first slide, slideshow stopped
slider.currentIndex; // getter, and settable
slider.slides; // the original <img> elements
slider.addEventListener('slide-start', (e) => {
console.log(e.detail.index, e.detail.slide, e.detail.count);
});
slider.addEventListener('slide-end', (e) => { /* transition finished */ });slide-start and slide-end both bubble and cross the shadow boundary, and both
carry { index, slide, count }. They replace FlexSlider's start, before and
after callbacks.
Override the custom properties on the host:
flex-slider {
--fs-accent: #c2410c;
--fs-arrow-bg: rgba(255, 255, 255, .9);
--fs-arrow-fg: #c2410c;
--fs-dot: rgba(255, 255, 255, .5);
--fs-dot-active: #fff;
--fs-radius: 12px;
}For anything deeper, the shadow parts are frame, track, pager, arrow-prev
and arrow-next:
flex-slider::part(frame) { border-radius: 12px; }
flex-slider::part(arrow-next) { width: 48px; height: 48px; }The suite in test/ runs in a real browser, because that is the only
environment where a web component can genuinely be verified — real layout, real
transitions, real events.
python3 -m http.server 8080
# then open http://localhost:8080/test/index.htmlIt covers construction, layout geometry, navigation, pointer gestures, animation,
the slideshow, events, accessibility, theming and live updates, and prints a
pass/fail summary on the page. There are no dependencies and no test framework:
index.html loads the component and the fixtures, harness.js provides the
runner and assertions, and suite.js holds the cases. The verdict is also
published on window.__flexSliderTests for anyone wiring this into CI.
Custom elements v1, Shadow DOM v1, CSS transitions, ResizeObserver and Pointer
Events — current Chrome, Edge, Firefox and Safari, plus recent iOS and Android
browsers. If you must support older browsers, keep a legacy slider for those
clients behind a feature check.
| FlexSlider 2 | <flex-slider> |
|---|---|
$('.flexslider').flexslider({...}) |
write <flex-slider> attributes |
animation: "slide" |
animation="slide" |
animationSpeed: 600 |
duration="600" |
slideshow: true |
autoplay |
slideshowSpeed: 7000 |
interval="7000" |
pauseOnHover: true |
pause-on-hover |
directionNav: true |
nav |
controlNav: true |
pager |
controlNav: "thumbnails" |
pager thumbs |
startAt: 2 |
slide-show-at="2" |
direction: "vertical" |
direction="vertical" |
smoothHeight: true |
smooth-height |
touch: false |
swipe="off" |
keyboard: true |
keyboard (on by default) |
rtl: true |
rtl |
namespace, selector |
not needed — structure is fixed |
useCSS, easing, mousewheel, video |
dropped — native CSS transitions only |
start / before / after callbacks |
slide-start / slide-end events |
$el.data('flexslider') |
the element itself is the API |
initDelay, randomize |
dropped |
Carousel mode (itemWidth, itemMargin, minItems, maxItems, move) and the
Vimeo/Wistia video slides are intentionally out of scope: this rewrite covers the
image slider, which is what FlexSlider was overwhelmingly used for.
GPL-2.0-or-later. This component is derived from FlexSlider 2, © 2012 WooThemes, contributing author Tyler Smith, and is distributed under the same licence. See LICENSE.md.