# Carousel plugin

**Cloudimage JS Carousel** is a high-performance, responsive image slider and gallery plugin designed to deliver high-quality visuals without compromising on page speed. By integrating seamlessly with the Cloudimage CDN, it automatically optimizes, resizes, and delivers images in the most efficient format for your users' devices.

Whether you need a simple homepage slider or a feature-rich product gallery with thumbnails and zoom, JS Carousel provides a lightweight, dependency-free solution.

### Why JS Carousel?

* Integrated Optimization: Leverages Cloudimage’s on-the-fly resizing to ensure users never download larger files than their screen requires.
* Gallery & Zoom: Includes built-in support for thumbnails and a full-screen lightbox mode with deep zoom capabilities.
* Framework Agnostic: Written in pure JavaScript (Vanilla JS). Works perfectly with React, Vue, Angular, or standard HTML.
* SEO & UX Friendly: Built with lazy loading and semantic HTML to improve Core Web Vitals and search engine ranking.

***

### Key Features

* Responsive by Design: Automatically adapts to any container size and device resolution.
* Transition Effects: Choose between smooth `slide` or elegant `fade` transitions.
* Smart Thumbnails: Generate an interactive thumbnail navigation bar with a single configuration.
* Lightbox Zoom: Integrated "click-to-zoom" functionality for high-resolution inspection.
* Autoplay & Loop: Fully configurable autoplay with pause-on-hover and infinite cycling.
* Touch Optimized: Native-feeling swipe gestures for mobile and tablet users.
* Highly Accessible: Includes support for bullet navigation, arrow controls, and keyboard shortcuts.

***

### Quick Start

Get your carousel up and running in minutes via our CDN or your favorite package manager.

#### 1. Installation

Using CDN:

```html
<script src="https://scaleflex.cloudimg.io/v7/plugins/js-carousel/latest/js-carousel.min.js"></script>
```

Using NPM:

```bash
npm install js-carousel
```

#### 2. Basic Usage

Define a container in your HTML and initialize the carousel with your image list.

```html
<div id="my-carousel"></div>

<script>
  const carousel = new window.CloudImageCarousel('#my-carousel', {
    images: [
      'https://sample.li/img1.jpg',
      'https://sample.li/img2.jpg',
      'https://sample.li/img3.jpg'
    ],
    autoplay: true,
    transitionEffect: 'slide'
  });
</script>
```

***

### Configuration Options

Tailor the carousel to your design needs using the following configuration parameters:

| **Parameter**      | **Type** | **Default** | **Description**                                           |
| ------------------ | -------- | ----------- | --------------------------------------------------------- |
| `images`           | Array    | `[]`        | List of image URLs to display.                            |
| `transitionEffect` | String   | `'slide'`   | Transition style: `'slide'` or `'fade'`.                  |
| `autoplay`         | Boolean  | `false`     | Enables automatic sliding.                                |
| `autoplayInterval` | Number   | `3000`      | Delay between slides in milliseconds.                     |
| `showThumbnails`   | Boolean  | `true`      | Displays a thumbnail navigation bar below the main image. |
| `showBullets`      | Boolean  | `false`     | Displays dot navigation.                                  |
| `cycle`            | Boolean  | `true`      | Enables infinite looping of slides.                       |
| `zoom`             | Boolean  | `true`      | Enables the lightbox zoom feature on click.               |

#### Example: Product Gallery with Thumbnails

```javascript
new CloudImageCarousel('#product-gallery', {
  images: [...],
  showThumbnails: true,
  showControls: true,
  showFilenames: false,
  ratio: 1.5 // Maintain a specific aspect ratio
});
```

***

### Performance & Optimization

To maintain peak performance, the plugin includes:

* Automatic WebP/AVIF: Cloudimage automatically serves the best format based on browser support.
* Lazy Loading: Images are only requested as they approach the viewport or the next slide position.
* Debounced Resizing: Efficiently handles window resizing to prevent layout shifts.

***

### Resources & Support

* Interactive Demo: [View JS Carousel in Action](https://scaleflex.cloudimg.io/v7/plugins/js-carousel/carousel-demo.html)
* GitHub Repository: [Scaleflex/js-carousel](https://github.com/scaleflex/js-carousel)
* For issues or feature requests: open a [GitHub Issue](https://github.com/scaleflex/js-carousel/issues) or contact us at <hello@cloudimage.io>.