Javascript/TypeScript image cloud library with custom loaders, various layouts, full images styling, with animation and zoom effects
npm install @frybynite/image-cloudA 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.
> [!WARNING]
> ⚠️ All minor versions of this library before 1.0 (e.g., 0.1, 0.2, ...) will include breaking changes during development. Please re-test every time before upgrading until we have published v1.0.
- ✨ Animated image layouts with smooth transitions
- 🎯 Multiple layout algorithms (radial, grid, spiral, cluster, wave, random)
- 🎬 Rich entry animations (bounce, elastic, wave paths; spin, wobble rotations)
- 🔍 Zoom/focus interactions with keyboard 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)
- 🛠️ Interactive configurator for visual configuration
- 📦 Zero runtime dependencies
- 🔷 Full TypeScript support
``bash`
npm install @frybynite/image-cloud
No install needed — load directly from a CDN:
jsDelivr
``
https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/image-cloud.js (ESM)
https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/image-cloud.umd.js (UMD)
https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/image-cloud-auto-init.js
https://cdn.jsdelivr.net/npm/@frybynite/image-cloud@latest/dist/style.css
unpkg
``
https://unpkg.com/@frybynite/image-cloud@latest/dist/image-cloud.js (ESM)
https://unpkg.com/@frybynite/image-cloud@latest/dist/image-cloud.umd.js (UMD)
https://unpkg.com/@frybynite/image-cloud@latest/dist/image-cloud-auto-init.js
https://unpkg.com/@frybynite/image-cloud@latest/dist/style.css
Replace @latest with a specific version (e.g., @0.2.1) to pin to that release.
`typescript
import { ImageCloud } from '@frybynite/image-cloud';
import '@frybynite/image-cloud/style.css';
const cloud = new 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'
}
});
await cloud.init();
`
`html
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"
}
}'
>
`
For detailed configuration, see the documentation in the docs/ folder:
1. Loaders — Configure image sources (static URLs, JSON endpoints, local paths, Google Drive folders)
2. Layout Generators — Choose and customize layout algorithms (radial, grid, spiral, cluster, random)
3. Image Sizing — Control base sizes, variance, and responsive/adaptive behavior
4. Full Parameter Reference — Complete configuration options for animation, interaction, styling, and more
5. API Reference — TypeScript API documentation for the ImageCloud class, types, loaders, and generators
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.
- Click image: Focus/zoom the image
- Click outside: Unfocus current image
- Hover: Apply hover styling
- 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
- Resize: Responsive layout adjustment (debounced)
- Chrome/Edge: Latest 2 versions
- Firefox: Latest 2 versions
- Safari: Latest 2 versions
- Mobile: iOS Safari 12+, Chrome Android
Check out the examples/ directory for various usage patterns:esm-example.html
- - Modern ES module usagecdn-umd-example.html
- - Traditional script tag / CDN usageauto-init-example.html
- - HTML data attribute initializationstatic-loader-example.html
- - Static image URLsstatic-urls-shorthand-example.html
- - Simplest static loader: direct URL array shorthandstatic-json-source-example.html
- - Load images from a JSON endpointgoogle-drive-loader-example.html
- - Google Drive folder sourcelayout-algorithms.html
- - Compare all layout algorithmsentry-animations.html
- - Entry animation stylesimage-style-demo.html
- - Borders, shadows, and filterstypescript-example.ts
- - TypeScript with React and Vueexamples/README.md` for detailed instructions
- See
Contributions are welcome! Please feel free to submit a Pull Request.
See docs/DEVELOPER.md for build scripts, testing, and project structure.
MIT