Image Cloud Library

A TypeScript library for creating interactive image clouds with animated scattered layouts and zoom effects. Supports multiple image sources (static URLs, JSON endpoints, Google Drive) and layout algorithms.

Features

• ✨ Animated image layouts with smooth transitions
• 🎯 Multiple layout algorithms (radial, grid, spiral, cluster, wave, honeycomb, random)
• 🎬 Rich entry animations (bounce, elastic, wave paths; spin, wobble rotations)
• 🔍 Zoom/focus interactions with keyboard, swipe, and click navigation
• 🎨 State-based image styling (borders, shadows, filters for default/hover/focused)
• 📱 Responsive design with adaptive sizing
• 🖼️ Multiple image sources (static URLs, JSON endpoints, Google Drive, composite loaders)
• ⚛️ Framework wrappers for React, Vue 3, and Web Components
• 🛠️ Interactive configurator for visual configuration
• 📦 Zero runtime dependencies
• 🔷 Full TypeScript support

Installation

npm install @frybynite/image-cloud

CDN

No install needed — load directly from a CDN:

jsDelivr

https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/image-cloud.js              (Main - ESM)
https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/image-cloud.umd.js          (Main - UMD)
https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/image-cloud-auto-init.js    (Auto-init)
https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/style.css

unpkg

https://unpkg.com/@frybynite/image-cloud@latest/dist/image-cloud.js              (Main - ESM)
https://unpkg.com/@frybynite/image-cloud@latest/dist/image-cloud.umd.js          (Main - UMD)
https://unpkg.com/@frybynite/image-cloud@latest/dist/image-cloud-auto-init.js    (Auto-init)
https://unpkg.com/@frybynite/image-cloud@latest/dist/style.css

Replace @latest with a specific version (e.g., @1.0.0) to pin to that release.

Quick Start

TypeScript/JavaScript (Programmatic API)

import { imageCloud } from '@frybynite/image-cloud';
import '@frybynite/image-cloud/style.css';

// Single-expression initialization — imageCloud() constructs and calls init() for you
const cloud = await imageCloud({
  container: 'myCloud',
  images: [
    'https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg?auto=compress&w=600',
    'https://images.pexels.com/photos/3225517/pexels-photo-3225517.jpeg?auto=compress&w=600',
    'https://images.pexels.com/photos/1402787/pexels-photo-1402787.jpeg?auto=compress&w=600'
  ],
  layout: {
    algorithm: 'radial'
  }
});

For advanced lifecycle control (e.g. deferred init, re-use), the ImageCloud class is also exported and still works as before:

const cloud = new ImageCloud({ container: 'myCloud', images: [...] });
await cloud.init();

React

npm install @frybynite/image-cloud react react-dom

import { ImageCloud } from '@frybynite/image-cloud/react';
import '@frybynite/image-cloud/style.css';

function App() {
  return (
    <ImageCloud
      style={{ width: '100%', height: '80vh' }}
      images={[
        'https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg?auto=compress&w=600',
        'https://images.pexels.com/photos/3225517/pexels-photo-3225517.jpeg?auto=compress&w=600',
        'https://images.pexels.com/photos/1402787/pexels-photo-1402787.jpeg?auto=compress&w=600'
      ]}
      layout={{ algorithm: 'radial' }}
    />
  );
}

Vue 3

npm install @frybynite/image-cloud vue

<script setup>
import { ImageCloud } from '@frybynite/image-cloud/vue';
import '@frybynite/image-cloud/style.css';

const options = {
  images: [
    'https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg?auto=compress&w=600',
    'https://images.pexels.com/photos/3225517/pexels-photo-3225517.jpeg?auto=compress&w=600',
    'https://images.pexels.com/photos/1402787/pexels-photo-1402787.jpeg?auto=compress&w=600'
  ],
  layout: { algorithm: 'radial' }
};
</script>

<template>
  <ImageCloud :options="options" style="width: 100%; height: 80vh" />
</template>

Web Component

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/style.css">
<script type="module">
  import '@frybynite/image-cloud/web-component';
</script>

<image-cloud
  style="display: block; width: 100%; height: 80vh"
  images='["https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg?auto=compress&w=600","https://images.pexels.com/photos/3225517/pexels-photo-3225517.jpeg?auto=compress&w=600","https://images.pexels.com/photos/1402787/pexels-photo-1402787.jpeg?auto=compress&w=600"]'
  layout="radial"
></image-cloud>

HTML (Auto-initialization)

<!DOCTYPE html>
<html>
<body>
  <div
    id="cloud"
    style="width: 100%; height: 100vh"
    data-image-cloud
    data-config='{
      "images": [
        "https://images.pexels.com/photos/1261728/pexels-photo-1261728.jpeg?auto=compress&w=600",
        "https://images.pexels.com/photos/3225517/pexels-photo-3225517.jpeg?auto=compress&w=600",
        "https://images.pexels.com/photos/1402787/pexels-photo-1402787.jpeg?auto=compress&w=600"
      ],
      "layout": {
        "algorithm": "radial"
      }
    }'
  ></div>

  <!-- No CSS link needed — auto-init injects styles automatically -->
  <script type="module" src="https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/image-cloud-auto-init.js"></script>
</body>
</html>

Getting Started

Full documentation is available at frybynite.github.io/image-cloud

• Loaders — Configure image sources (static URLs, JSON endpoints, Google Drive)
• Layouts — Layout algorithms (radial, grid, spiral, cluster, wave, honeycomb, random)
• Image Sizing — Base sizes, variance, and responsive/adaptive behavior
• Framework Wrappers — React, Vue 3, and Web Component usage
• Parameters — Complete configuration reference
• API Reference — TypeScript API documentation

Using the Configurator

The easiest way to create a custom configuration is with the interactive Configurator tool:

• Online: Image Cloud Configurator
• Local: Run a local server from the configurator/ directory

The Configurator lets you visually adjust all settings and exports a ready-to-use JSON configuration.

Events & Interactions

Mouse

• Click image: Focus/zoom the image
• Click outside: Unfocus current image
• Hover: Apply hover styling

Keyboard

• Arrow Right: Navigate to next image (when focused)
• Arrow Left: Navigate to previous image (when focused)
• Enter / Space: Focus hovered image
• Escape: Unfocus current image

Touch

• Swipe left / right: Navigate between focused images

Window

• Resize: Responsive layout adjustment (debounced)

Browser Support

• Chrome/Edge: Latest 2 versions
• Firefox: Latest 2 versions
• Safari: Latest 2 versions
• Mobile: iOS Safari 12+, Chrome Android

Examples

Live examples are published at frybynite.github.io/image-cloud/examples/:

• Static URLs Shorthand - Simplest setup: direct URL array
• Static Loader - Static image URLs
• Static JSON Source - Load images from a JSON endpoint
• Google Drive - Google Drive folder source
• Auto-Init - Zero-JS setup using data attributes
• ESM Module - ES module usage
• CDN/UMD - CDN script tag usage
• Iframe Embed - Embedded in an iframe
• Layout Algorithms - Compare all layout algorithms
• Entry Animations - Entry animation styles
• Keyboard Navigation - Per-container keyboard navigation
• Image Style Demo - Borders, shadows, and filters
• Detailed Styling - In-depth styling examples

Changelog

See Changelog for a full list of changes across all versions.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

See the Developer Guide for build scripts, testing, and project structure.

License

MIT

Author

frybynite