---
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Usage](#usage)
- [2D Grid Mode](#2d-grid-mode)
- [React / Next.js](#react--nextjs)
- [Configuration Options](#configuration-options)
- [Event Callbacks](#event-callbacks)
- [Hotspots](#hotspots)
- [Interaction Hints](#interaction-hints)
- [Styling & Theming](#styling--theming)
- [Methods](#methods)
- [Cloudimage Integration](#cloudimage-integration)
- [Browser Support](#browser-support)
- [Migration Guide (v3 → v4)](#migration-guide-v3--v4)
- [Contributing](#contributing)
- [Support](#support)
- [License](#license)
---
## Overview
JS Cloudimage 360 View enables you to create stunning, interactive 360-degree product views for your website. Perfect for e-commerce platforms, virtual tours, and product showcases, it provides an immersive viewing experience that lets users explore products from every angle.
### Why Choose This Library?
- **Easy Integration** - Get started in minutes with CDN or npm
- **Fully Customizable** - CSS variables, callbacks, and extensive configuration options
- **Mobile-Friendly** - Touch and swipe support out of the box
- **Performance Optimized** - Lazy loading, responsive images, and efficient rendering
- **Feature Rich** - Hotspots, zoom, fullscreen, autoplay, and more
---
## Features
| Feature | Description |
|---------|-------------|
| **360° Rotation** | Smooth horizontal and vertical rotation with customizable speed |
| **2D Grid Mode** | True two-axis viewing for images organized as a horizontal/vertical matrix |
| **Touch & Drag** | Intuitive mouse and touch controls with inertia/momentum |
| **Pinch-to-Zoom** | Natural pinch gesture zooming on mobile devices |
| **Autoplay** | Automatic rotation with configurable behavior and direction |
| **Zoom** | Double-click, Ctrl+scroll, or pinch-to-zoom with pan controls |
| **Fullscreen** | Immersive fullscreen mode with ESC key support |
| **Hotspots** | Interactive markers with tooltips for highlighting features |
| **Keyboard Navigation** | Arrow key support for accessibility |
| **Lazy Loading** | Optimized loading for better performance |
| **Responsive** | Works on all screen sizes with Cloudimage CDN integration |
| **Theming** | CSS variables for easy customization |
| **Event Callbacks** | Hook into viewer lifecycle and user interactions |
---
## Quick Start
Add the library via CDN and create your first 360 viewer in seconds:
```html
```
---
## Installation
### Option 1: CDN (Recommended for Quick Setup)
```html
```
> **Note:** CSS is automatically injected by the script - no separate stylesheet needed.
### Option 2: Package Manager
```bash
# npm
npm install js-cloudimage-360-view
# yarn
yarn add js-cloudimage-360-view
# pnpm
pnpm add js-cloudimage-360-view
```
Then import in your JavaScript:
```javascript
import CI360 from 'js-cloudimage-360-view';
import 'js-cloudimage-360-view/css';
```
---
## Usage
### Method 1: Data Attributes (Declarative)
The simplest way to create a 360 viewer using HTML data attributes:
```html
```
### Method 2: JavaScript Configuration (Programmatic)
For more control, initialize with a JavaScript configuration object:
```javascript
const viewer = new CI360();
const container = document.getElementById('product-viewer');
const config = {
folder: 'https://your-domain.com/images/',
filenameX: 'product-{index}.jpg',
amountX: 36,
autoplay: true,
speed: 100,
dragSpeed: 150,
fullscreen: true,
zoomMax: 3,
inertia: true,
// Event callbacks
onReady: () => console.log('Viewer ready!'),
onSpin: (e) => console.log(`Frame: ${e.activeImageX + 1}/${e.amountX}`),
};
viewer.init(container, config);
```
### X and Y Axis Rotation
Support 360° rotation on both axes for full product exploration:
```javascript
const config = {
folder: 'https://your-domain.com/images/',
filenameX: 'product-x-{index}.jpg',
filenameY: 'product-y-{index}.jpg',
amountX: 36,
amountY: 18,
autoplayBehavior: 'spin-xy', // Options: 'spin-x', 'spin-y', 'spin-xy', 'spin-yx'
};
```
### 2D Grid Mode
For products photographed at multiple horizontal **and** vertical angles, grid mode provides true two-axis viewing. Instead of independent X/Y strips, the displayed image is determined by both axes simultaneously — dragging horizontally changes X, vertically changes Y, and diagonal drags update both.
Grid mode is auto-detected when `filenameGrid` or `imageListGrid` is provided.
**Using a filename pattern:**
```javascript
CI360.init(document.getElementById('viewer'), {
folder: 'https://your-domain.com/images/',
filenameGrid: 'product_{indexY}_{indexX}.jpg',
amountX: 24, // horizontal angles
amountY: 4, // vertical angles
indexZeroBase: 3, // zero-pad to 3 digits: 001, 002, ...
stopAtEdgesY: true, // prevent Y from looping
});
```
Placeholders `{indexX}` and `{indexY}` are replaced with 1-based indices (respecting `indexZeroBase` for zero-padding). Images are stored internally as a flat array with the formula `imagesGrid[y * amountX + x]`.
**Using an explicit image list:**
```javascript
CI360.init(document.getElementById('viewer'), {
imageListGrid: [
// y=0 row (all X frames at first vertical angle)
'img_001_001.jpg', 'img_001_002.jpg', /* ... */
// y=1 row
'img_002_001.jpg', 'img_002_002.jpg', /* ... */
],
amountX: 24,
amountY: 4,
});
```
**Autoplay** works with all four behaviors: `spin-x` (horizontal only), `spin-y` (vertical only), `spin-xy` (row-scan: X advances each tick, Y advances when X wraps), and `spin-yx` (column-scan).
**Per-axis edge stopping** — use `stopAtEdgesX` and `stopAtEdgesY` to control looping independently. This is useful when one axis has full 360° coverage but the other has limited angles:
```javascript
{
stopAtEdgesY: true, // Y has only 4 angles, don't loop
// X loops freely (default)
}
```
**React:**
```tsx
```
---
## React / Next.js
The library provides a React wrapper for seamless integration with React and Next.js applications.
### Installation
```bash
npm install js-cloudimage-360-view
```
### Basic Usage
```tsx
import { CI360Viewer } from 'js-cloudimage-360-view/react';
import 'js-cloudimage-360-view/css';
function ProductView() {
return (
);
}
```
### Imperative Control with Ref
Use a ref to control the viewer programmatically:
```tsx
import { useRef } from 'react';
import { CI360Viewer, CI360ViewerRef } from 'js-cloudimage-360-view/react';
import 'js-cloudimage-360-view/css';
function ProductView() {
const viewerRef = useRef(null);
return (
<>
console.log(`Frame: ${e.activeImageX}`)}
/>
);
}
```
### Available Ref Methods
| Method | Description |
|--------|-------------|
| `play()` | Start autoplay |
| `stop()` | Stop autoplay |
| `moveLeft(steps?)` | Move left by specified frames (default: 1) |
| `moveRight(steps?)` | Move right by specified frames (default: 1) |
| `moveTop(steps?)` | Move up on Y-axis (default: 1) |
| `moveBottom(steps?)` | Move down on Y-axis (default: 1) |
| `zoomIn()` | Toggle zoom in |
| `zoomOut()` | Zoom out |
| `goToFrame(frame, hotspotId?)` | Animate to specific frame |
| `getViewer()` | Get underlying viewer instance |
### With Hotspots
```tsx
import { CI360Viewer, Hotspot } from 'js-cloudimage-360-view/react';
const hotspots: Hotspot[] = [
{
id: 'feature-1',
label: 'Engine',
orientation: 'x',
containerSize: [1200, 800],
positions: { 0: { x: 500, y: 300 } },
content: '
Engine details
',
},
];
function ProductView() {
return (
);
}
```
### Next.js (SSR)
For Next.js applications, use dynamic import to disable server-side rendering:
```tsx
import dynamic from 'next/dynamic';
import 'js-cloudimage-360-view/css';
const CI360Viewer = dynamic(
() => import('js-cloudimage-360-view/react').then(mod => mod.CI360Viewer),
{ ssr: false }
);
export default function ProductPage() {
return (
);
}
```
### useCI360 Hook
For advanced use cases, you can use the `useCI360` hook directly:
```tsx
import { useRef } from 'react';
import { useCI360 } from 'js-cloudimage-360-view/react';
function CustomViewer() {
const containerRef = useRef(null);
const { viewer, isReady } = useCI360(containerRef, {
folder: 'https://example.com/images/',
filenameX: '{index}.jpg',
amountX: 36,
onReady: () => console.log('Viewer ready!'),
});
return (
{isReady &&
Viewer is ready!
}
);
}
```
### TypeScript Support
The React wrapper is fully typed. Import types as needed:
```tsx
import type {
CI360ViewerProps,
CI360ViewerRef,
CI360Config,
SpinEventData,
Hotspot,
} from 'js-cloudimage-360-view/react';
```
---
## Configuration Options
All options can be set via JavaScript config or HTML data attributes.
### Image Source Options
| Option | Data Attribute | Default | Description |
|--------|----------------|---------|-------------|
| `folder` | `data-folder` | `'/'` | Path to the folder containing images |
| `filenameX` | `data-filename-x` | `'image-{index}.jpg'` | Filename pattern for X-axis images. Use `{index}` as placeholder |
| `filenameY` | `data-filename-y` | `null` | Filename pattern for Y-axis images |
| `imageListX` | `data-image-list-x` | `null` | Array of image URLs for X-axis (alternative to folder/filename) |
| `imageListY` | `data-image-list-y` | `null` | Array of image URLs for Y-axis |
| `filenameGrid` | `data-filename-grid` | `null` | Filename pattern for 2D grid mode. Uses `{indexX}` and `{indexY}` placeholders |
| `imageListGrid` | `data-image-list-grid` | `null` | Array of image URLs for 2D grid (flat or 2D array, Y-outer X-inner order) |
| `amountX` | `data-amount-x` | `0` | Total number of X-axis images |
| `amountY` | `data-amount-y` | `0` | Total number of Y-axis images |
| `indexZeroBase` | `data-index-zero-base` | `0` | Starting index for image filenames |
### Behavior Options
| Option | Data Attribute | Default | Description |
|--------|----------------|---------|-------------|
| `autoplay` | `data-autoplay` | `false` | Enable automatic rotation |
| `autoplayBehavior` | `data-autoplay-behavior` | `'spin-x'` | Autoplay pattern: `'spin-x'`, `'spin-y'`, `'spin-xy'`, `'spin-yx'` |
| `autoplayReverse` | `data-autoplay-reverse` | `false` | Reverse autoplay direction |
| `playOnce` | `data-play-once` | `false` | Stop after one complete rotation |
| `speed` | `data-speed` | `80` | Autoplay speed (ms between frames) |
| `inertia` | `data-inertia` | `false` | Enable momentum after drag release |
### Control Options
| Option | Data Attribute | Default | Description |
|--------|----------------|---------|-------------|
| `draggable` | `data-draggable` | `true` | Enable mouse drag rotation |
| `swipeable` | `data-swipeable` | `true` | Enable touch swipe rotation |
| `dragSpeed` | `data-drag-speed` | `150` | Drag sensitivity |
| `dragReverse` | `data-drag-reverse` | `false` | Reverse drag direction |
| `keys` | `data-keys` | `false` | Enable keyboard arrow navigation |
| `keysReverse` | `data-keys-reverse` | `false` | Reverse keyboard direction |
| `stopAtEdges` | `data-stop-at-edges` | `false` | Stop rotation at first/last frame (both axes) |
| `stopAtEdgesX` | `data-stop-at-edges-x` | `null` | Stop X-axis at edges. Overrides `stopAtEdges` for X when set |
| `stopAtEdgesY` | `data-stop-at-edges-y` | `null` | Stop Y-axis at edges. Overrides `stopAtEdges` for Y when set |
| `pinchZoom` | `data-pinch-zoom` | `true` | Enable pinch-to-zoom on touch devices |
### Display Options
| Option | Data Attribute | Default | Description |
|--------|----------------|---------|-------------|
| `aspectRatio` | `data-aspect-ratio` | `null` | Aspect ratio for the container (e.g., `"16/9"`, `"4/3"`, `"1/1"`) |
| `fullscreen` | `data-fullscreen` | `false` | Show fullscreen button |
| `zoomMax` | `data-zoom-max` | `5` | Maximum zoom level (1-10) |
| `zoomStep` | `data-zoom-step` | `0.5` | Zoom increment per step |
| `zoomControls` | `data-zoom-controls` | `true` | Show zoom control buttons (zoom in, zoom out, reset) |
| `zoomControlsPosition` | `data-zoom-controls-position` | `'bottom-right'` | Position of zoom controls toolbar. Values: `'top-left'`, `'top-center'`, `'top-right'`, `'bottom-left'`, `'bottom-center'`, `'bottom-right'` |
| `scrollHint` | `data-scroll-hint` | `true` | Show "Ctrl + scroll to zoom" hint on scroll |
| `bottomCircle` | `data-bottom-circle` | `false` | Show 360° progress indicator |
| `bottomCircleOffset` | `data-bottom-circle-offset` | `5` | Progress indicator offset (px) |
| `initialIconShown` | `data-initial-icon` | `true` | Show 360° icon on load |
| `initOnClick` | `data-init-on-click` | `false` | If true, images load only after the user clicks on the viewer. Shows a first-frame preview with a click overlay. Useful for grids with multiple 360 views |
| `lazyload` | `data-lazyload` | `true` | Enable lazy loading |
| `hints` | `data-hints` | `true` | Show interaction hints on load |
| `theme` | `data-theme` | `null` | Color theme: `'light'` or `'dark'` |
| `hotspotTrigger` | `data-hotspot-trigger` | `'hover'` | Hotspot trigger mode: `'hover'` or `'click'` |
| `hotspotTimelineOnClick` | `data-hotspot-timeline-on-click` | `true` | Show hotspot popup when clicking timeline dot |
| `markerTheme` | `data-marker-theme` | `null` | Hotspot marker theme: `'default'`, `'inverted'`, or `'brand'` |
| `brandColor` | `data-brand-color` | `null` | Brand accent color for `'brand'` marker theme (e.g. `'#ff6600'`) |
### Cloudimage CDN Options
| Option | Data Attribute | Default | Description |
|--------|----------------|---------|-------------|
| `ciToken` | `data-responsive` | `null` | Cloudimage token for responsive images |
| `ciFilters` | `data-filters` | `null` | Cloudimage filters |
| `ciTransformation` | `data-transformation` | `null` | Cloudimage transformations |
---
## Event Callbacks
Hook into viewer events for custom functionality. Callbacks are only available via JavaScript configuration.
| Callback | Event Data | Description |
|----------|------------|-------------|
| `onReady` | `{ viewerId }` | Viewer initialized and ready |
| `onLoad` | `{ viewerId, imagesX, imagesY }` | All images loaded |
| `onSpin` | `{ viewerId, direction, activeImageX, activeImageY, amountX, amountY }` | Each rotation frame |
| `onAutoplayStart` | `{ viewerId }` | Autoplay started |
| `onAutoplayStop` | `{ viewerId }` | Autoplay stopped |
| `onDragStart` | `{ viewerId }` | User started dragging |
| `onDragEnd` | `{ viewerId }` | User stopped dragging |
| `onZoomIn` | `{ viewerId, zoomLevel }` | Pointer zoom activated |
| `onZoomOut` | `{ viewerId }` | Pointer zoom deactivated |
| `onFullscreenOpen` | `{ viewerId }` | Fullscreen mode opened |
| `onFullscreenClose` | `{ viewerId }` | Fullscreen mode closed |
### Example
```javascript
const config = {
folder: 'https://example.com/images/',
filenameX: '{index}.jpg',
amountX: 36,
onReady: (e) => {
console.log(`Viewer ${e.viewerId} is ready`);
},
onSpin: (e) => {
// Update custom progress indicator
const progress = ((e.activeImageX + 1) / e.amountX * 100).toFixed(0);
document.getElementById('progress').textContent = `${progress}%`;
},
onFullscreenOpen: () => {
// Pause background video when entering fullscreen
document.getElementById('bg-video')?.pause();
},
};
```
---
## Hotspots
Add interactive markers to highlight product features.
### Configuration
```javascript
const hotspots = [
{
id: 'feature-1',
orientation: 'x',
containerSize: [1200, 800], // Reference container size for positioning
positions: {
0: { x: 500, y: 300 },
1: { x: 520, y: 300 },
2: { x: 540, y: null }, // null inherits from previous frame
3: { x: 560, y: null },
// ... positions for frames where hotspot is visible
},
content: '
Premium Feature
Description here
',
onClick: () => {
console.log('Hotspot clicked!');
},
},
];
const config = {
folder: 'https://example.com/images/',
filenameX: '{index}.jpg',
amountX: 36,
hotspots: hotspots,
};
```
### Hotspot Properties
| Property | Required | Description |
|----------|----------|-------------|
| `id` | Yes | Unique identifier |
| `orientation` | Yes | `'x'` or `'y'` axis |
| `containerSize` | Yes | `[width, height]` reference dimensions |
| `positions` | Yes | Object mapping frame index to `{ x, y }` coordinates |
| `content` | No | HTML content for the tooltip |
| `label` | No | Short label for the hotspot (used in timeline tooltips) |
| `onClick` | No | Click handler function |
| `keepOpen` | No | If `true`, the popover stays open until explicitly closed |
| `className` | No | Custom CSS class(es) to add to the hotspot element |
| `markerTheme` | No | Per-hotspot theme override: `'default'`, `'inverted'`, or `'brand'` |
| `navigateTo` | No | Scene ID to navigate to on click (turns hotspot into a navigation pin) |
| `arrowDirection` | No | Rotation angle (degrees) for the navigation arrow icon. Only applies when `navigateTo` is set |
### Hotspot Timeline
When hotspots are configured, a timeline navigation bar automatically appears below the viewer. This timeline shows:
- **Position indicator** - Shows current rotation position
- **Hotspot dots** - One dot per hotspot at its center frame position
- **Hover tooltips** - If a hotspot has a `label`, hovering over its dot shows a tooltip
Clicking a dot animates the viewer to that hotspot's position and optionally shows its popup.
#### Timeline Tooltips
Tooltips display the hotspot's `label` property when hovering over a timeline dot:
```javascript
const hotspots = [
{
id: 'engine',
label: 'Engine Bay', // This text appears in the tooltip
orientation: 'x',
containerSize: [1200, 800],
positions: { 0: { x: 500, y: 300 }, /* ... */ },
content: '
Full hotspot content here
',
},
];
```
**Tooltip behavior:**
- Appears after a **400ms hover delay** to prevent accidental triggers
- Positioned above the dot with an arrow pointer
- Hidden on mouse leave or click (navigation)
#### Timeline Configuration
| Option | Default | Description |
|--------|---------|-------------|
| `hotspotTimelineOnClick` | `true` | Show hotspot popup when clicking a timeline dot |
```javascript
const config = {
hotspots: [...],
hotspotTimelineOnClick: true, // Show popup on click (default)
// or
hotspotTimelineOnClick: false, // Only navigate, don't show popup
};
```
#### Timeline CSS Variables
Customize the timeline appearance with CSS variables:
```css
:root {
/* Timeline track */
--ci360-timeline-height: 6px;
--ci360-timeline-track-bg: rgba(0, 0, 0, 0.12);
/* Hotspot dots */
--ci360-timeline-dot-size: 18px;
--ci360-timeline-dot-color: var(--ci360-hotspot-color);
--ci360-timeline-dot-border: 2px solid #fff;
/* Position indicator */
--ci360-timeline-indicator-size: 12px;
--ci360-timeline-indicator-color: #333333;
/* Tooltip styling (matches theme) */
--ci360-timeline-tooltip-bg: rgba(255, 255, 255, 0.95);
--ci360-timeline-tooltip-color: #333333;
}
/* Dark theme uses dark tooltip */
.ci360-theme-dark {
--ci360-timeline-tooltip-bg: rgba(40, 40, 45, 0.95);
--ci360-timeline-tooltip-color: #e0e0e0;
}
```
**Custom tooltip styling example:**
```css
/* Increase tooltip font size */
.cloudimage-360-hotspot-timeline-tooltip {
font-size: 14px;
padding: 8px 16px;
}
/* Brand-colored tooltip */
.my-viewer {
--ci360-timeline-tooltip-bg: #2563eb;
--ci360-timeline-tooltip-color: #ffffff;
}
```
### Marker Themes
Control the visual appearance of hotspot markers at the viewer level or per-hotspot.
**Viewer-level theme** applies to all hotspots:
```javascript
const config = {
hotspots: [...],
markerTheme: 'inverted', // 'default', 'inverted', or 'brand'
brandColor: '#ff6600', // Used when markerTheme is 'brand'
};
```
**Per-hotspot theme** overrides the viewer-level theme for individual markers:
```javascript
const hotspots = [
{
id: 'highlight',
markerTheme: 'brand', // Override for this hotspot only
positions: { 0: { x: 500, y: 300 } },
content: '
---
## License
This project is licensed under the [MIT License]([https://opensource.org/licenses/MIT](https://github.com/scaleflex/js-cloudimage-360-view/blob/master/LICENSE)).
---