# 360 View plugin

JS Cloudimage 360 View is a lightweight, high-performance JavaScript library that allows you to create interactive, 360-degree product views. By leveraging the power of the Cloudimage CDN, it delivers pixel-perfect, responsive images that allow your users to explore every detail of your products from any angle.

Perfect for e-commerce platforms, virtual tours, and product showcases, this plugin provides an immersive viewing experience with minimal effort and maximum performance.

### Why JS Cloudimage 360 View?

* Boost Engagement: Interactive content increases time-on-page and customer confidence, leading to higher conversion rates.
* Performance First: Built-in lazy loading and Cloudimage's on-the-fly resizing ensure that high-resolution 360° views don't slow down your website.
* Zero Dependencies: A lightweight library that works with Vanilla JS, React, and other modern frameworks without requiring heavy third-party libraries.
* Mobile Optimized: Smooth touch and swipe gestures, pinch-to-zoom, and smart memory management for a seamless mobile experience.

***

### Key Features

* 360° Rotation: Smooth horizontal (X) and vertical (Y) rotation with customizable inertia and speed.
* Interactive Hotspots: Add markers with tooltips or custom HTML to highlight specific product features.
* Deep Zoom: Integrated pointer zoom and magnifying glass functionality for high-detail inspection.
* Responsive & Adaptive: Automatically fetches the correctly sized images for the user's screen using the Cloudimage resizing engine.
* Fullscreen Mode: Immersive viewing experience with a dedicated UI and ESC-key support.
* Autoplay: Configurable "spin-on-load" behavior to grab user attention immediately.
* Fully Customizable: Control every aspect via CSS variables, data attributes, or a robust JavaScript API.

***

### Quick Start

Integrate the 360 viewer into your project in minutes using either our CDN or NPM.

#### 1. Installation

Using CDN (Recommended for quick setup):

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

Using NPM:

```bash
npm install js-cloudimage-360-view
```

#### 2. Basic Usage

Simply add a container with the `cloudimage-360` class and provide the path to your image set via data attributes.

```html
<div
  class="cloudimage-360"
  data-folder="https://scaleflex.cloudimg.io/v7/demo/360-car/"
  data-filename-x="car-{index}.jpg"
  data-amount-x="36"
></div>

<script>
  const viewer = new window.CI360();
  viewer.initAll();
</script>
```

***

### Configuration & Customization

The plugin is highly declarative. You can configure almost every feature directly in the HTML using `data-` attributes:

| **Attribute**     | **Description**                                              | **Default** |
| ----------------- | ------------------------------------------------------------ | ----------- |
| `data-folder`     | The base URL/folder where your images are stored.            | -           |
| `data-filename-x` | The pattern for X-axis images (e.g., `prod-{index}.jpg`).    | -           |
| `data-amount-x`   | Number of images for the horizontal rotation.                | 36          |
| `data-autoplay`   | Enable automatic rotation on load.                           | `false`     |
| `data-magnifier`  | Enable a magnifying glass with a specific scale (e.g., `2`). | -           |
| `data-speed`      | Animation/rotation speed in milliseconds.                    | 100         |

#### Advanced: Multi-axis View

Showcase your product from every possible angle by adding vertical rotation:

```html
<div 
  class="cloudimage-360"
  data-amount-x="36"
  data-amount-y="18"
  data-filename-x="product-x-{index}.jpg"
  data-filename-y="product-y-{index}.jpg"
></div>
```

***

### Interactive Hotspots

Enhance your product discovery by placing hotspots on specific frames. Hotspots can be configured via a JSON object or dynamically through the API.

```js
const hotspots = [
  {
    index: 10,
    x: 450,
    y: 300,
    tooltip: "Premium Leather Finish"
  }
];

viewer.addHotspots('my-viewer-id', hotspots);
```

***

### Performance & Optimization

To ensure a smooth experience even with 100+ high-res images, the plugin includes:

* Lazy Loading: Only loads the 360 view when it enters the viewport.
* Memory Management: Automatically releases image memory on mobile devices to prevent browser crashes.
* Web Worker Support: Offloads image processing to keep the main UI thread responsive.

***

### Resources & Support

* Live Demo & Playground: [Explore the Interactive Demo](https://scaleflex.github.io/js-cloudimage-360-view/)
* React Integration: [View React Component Docs](https://github.com/Scaleflex/js-cloudimage-360-view?tab=readme-ov-file#react--nextjs)
* GitHub Repository: [Scaleflex/js-cloudimage-360-view](https://github.com/Scaleflex/js-cloudimage-360-view)
* For issues or feature requests: open a [GitHub Issue](https://github.com/Scaleflex/js-cloudimage-360-view/issues) or contact us at <hello@cloudimage.io>.