A lightweight, accessible image carousel with zoom, swipe, theming, and CSS variable customization.
Two ways to install — npm for bundlers, CDN for quick prototyping.
For modern bundlers (Vite, Webpack, etc.)
yarn add @cloudimage/carousel
import CloudImageCarousel from '@cloudimage/carousel'
const carousel = new CloudImageCarousel('#el', {
images: ['photo1.jpg', 'photo2.jpg'],
theme: 'light',
})
carousel.init()
Zero-build setup with autoInit
<script src="https://unpkg.com/@cloudimage/carousel/dist/carousel.min.js"></script>
<div
data-ci-carousel-images='["photo1.jpg","photo2.jpg"]'
data-ci-carousel-theme="dark"
data-ci-carousel-show-bullets="true"
></div>
<script>CloudImageCarousel.autoInit()</script>
Built-in light and dark themes. Customize every detail with 30+ CSS custom properties.
theme: 'light' (default)
theme: 'dark'
CSS variable overrides
/* Custom navy blue theme — override any --ci-carousel-* variable */
.my-carousel .ci-carousel {
--ci-carousel-bg: #0f172a;
--ci-carousel-btn-bg: rgba(59, 130, 246, 0.85);
--ci-carousel-btn-color: #ffffff;
--ci-carousel-btn-hover-bg: rgba(59, 130, 246, 1);
--ci-carousel-bullet-active-bg: #3b82f6;
--ci-carousel-thumbnail-active-border: 0 0 0 2px #3b82f6;
--ci-carousel-thumbnails-bg: #0f172a;
}
Navigation arrows centered on sides or at the bottom. Fullscreen button always top-right.
controlsPosition: 'center'
controlsPosition: 'bottom'
Four built-in effects with configurable easing and duration via CSS variables.
transitionEffect: 'slide'
transitionEffect: 'fade'
transitionEffect: 'zoom'
transitionEffect: 'flip'
Configurable zoom constraints via zoomMin, zoomMax, and zoomStep. Try Ctrl+scroll (Cmd+scroll on Mac) or double-click to zoom.
zoomMin: 1, zoomMax: 4, zoomStep: 0.3
zoomMin: 1, zoomMax: 8, zoomStep: 0.5
new CloudImageCarousel('#el', {
images: [...],
zoomMin: 1, // minimum zoom level (default: 1)
zoomMax: 8, // maximum zoom level (default: 4)
zoomStep: 0.5, // zoom increment per step (default: 0.3)
}).init()
Toggle options and see the generated code update in real time.
WCAG 2.1 AA compliant. Alt text via { src, alt } objects, live region announcements, keyboard
navigation, and autoplay pause.
new CloudImageCarousel('#el', {
images: [
{ src: 'hotel.jpg', alt: 'Luxury hotel lobby' },
{ src: 'birds.jpg', alt: 'Colorful birds' },
],
showFilenames: true,
}).init()
Arrow keys to navigate, Escape to reset zoom. Focus indicators on all interactive elements.
ARIA roles, live region slide announcements, alt text, aria-pressed on bullets/thumbnails.
Ctrl+scroll, double-click, pinch-to-zoom. Scroll hint toast for discoverability.
prefers-reduced-motion disables all transitions and animations.