jquery.photocols.js

An animated photo gallery with scrolling columns and rows for jQuery. Supports vertical and horizontal scrolling with parallax effects.

Made by 2Coders Studio in Canary Islands

Features

• Multi-directional scrolling - Up, down, left, or right
• Variable speed per column/row - Create parallax effects
• Lazy loading - Images load only when entering viewport
• Pause on hover - Pause individual columns or entire gallery
• Hover effects with title/subtitle overlays
• Responsive layout that adapts to container width
• Multiple instance support
• TypeScript definitions included
• GPU-accelerated animations using CSS transforms
• Memory-safe with proper cleanup

Installation

npm

npm install jquery.photocols

Direct Download

Download the minified file and include it in your page:

<script src="jquery.photocols.min.js"></script>

CDN

Via unpkg:

<script src="https://unpkg.com/[email protected]/dist/jquery.photocols.min.js"></script>

Via jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.photocols.min.js"></script>

Usage

Create a container element:

<div id="photocols"></div>

Initialize the plugin with your photo data:

$(document).ready(function() {
  $('#photocols').photocols({
    height: 500,
    colswidth: 200,
    data: [
      { title: 'Mountain View', subtitle: 'Nature', url: '#', img: 'https://picsum.photos/seed/a/640/480' },
      { title: 'City Lights',   subtitle: 'Urban',  url: '#', img: 'https://picsum.photos/seed/b/640/480' },
      { title: 'Ocean Waves',   subtitle: 'Coast',  url: '#', img: 'https://picsum.photos/seed/c/640/480' }
    ]
  });
});

Options

Basic Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | bgcolor | CSS Color | '#000' | Background color of the container | | width | Integer/String | 'auto' | Container width (pixels or 'auto' for 100%) | | colswidth | Integer | 200 | Base width for calculating column count | | itemheight | Integer | 300 | Height of each photo item in pixels | | height | Integer | 600 | Total container height in pixels | | gap | Integer | 5 | Gap between items in pixels | | opacity | Float (0-1) | 0.3 | Overlay opacity on photos | | titleSize | Integer | 16 | Title font size in pixels | | subtitleSize | Integer | 14 | Subtitle font size in pixels | | overlayColor | CSS Color | '#000' | Color of the photo overlay | | stopOnHover | Boolean | true | Pause column/row animation on hover | | data | Array | [] | Array of photo item objects | | titleTop | Integer | 56 | Title vertical position from top of mask | | subtitleTop | Integer | 80 | Subtitle vertical position from top of mask | | maskHeight | Integer | 120 | Height of the hover mask | | animationSpeed | Integer | 1 | Animation speed in pixels per frame | | debounceDelay | Integer | 150 | Resize debounce delay in milliseconds |

Direction Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | direction | String | 'up' | Scroll direction: 'up', 'down', 'left', or 'right' |

Variable Speed Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | variableSpeed | Boolean | false | Enable variable speed per column/row for parallax effect | | speedVariation | Float (0-1) | 0.5 | Speed variation range (0.5 = 50% to 150% of base speed) |

Hover Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | pauseAllOnHover | Boolean | false | Pause entire gallery on hover (vs just active column/row) |

Lazy Loading Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | lazyLoad | Boolean | false | Enable lazy loading of images with IntersectionObserver | | lazyLoadThreshold | Integer | 100 | Pixels before viewport to start loading images | | placeholderColor | CSS Color | '#333' | Background color shown while image loads |

Data Format

Each item in the data array should have:

{
  title: 'Photo Title',       // Title shown on hover
  subtitle: 'Photo Subtitle', // Subtitle shown on hover
  url: 'https://...',         // Link URL when clicked
  img: 'https://...'          // Image URL
}

Examples

Horizontal Scrolling (Left to Right)

$('#gallery').photocols({
  direction: 'right',
  height: 400,
  data: myPhotos
});

Parallax Effect with Variable Speed

$('#gallery').photocols({
  variableSpeed: true,
  speedVariation: 0.6,  // 40% to 160% of base speed
  animationSpeed: 0.7,  // Slower for smooth parallax
  data: myPhotos
});

Pause Entire Gallery on Hover

$('#gallery').photocols({
  pauseAllOnHover: true,
  data: myPhotos
});

Lazy Loading for Large Galleries

$('#gallery').photocols({
  lazyLoad: true,
  lazyLoadThreshold: 150,
  placeholderColor: '#1a1a1a',
  data: myLargePhotoCollection
});

Combined Features

$('#gallery').photocols({
  direction: 'left',
  variableSpeed: true,
  speedVariation: 0.4,
  pauseAllOnHover: true,
  lazyLoad: true,
  height: 500,
  animationSpeed: 0.6,
  data: myPhotos
});

Methods

pause

Pause the animation:

$('#photocols').photocols('pause');

resume

Resume the animation:

$('#photocols').photocols('resume');

refresh

Rebuild the layout (useful after container resize):

$('#photocols').photocols('refresh');

destroy

Remove the plugin and clean up:

$('#photocols').photocols('destroy');

Global Defaults

You can modify the default options globally:

$.fn.photocols.defaults.height = 800;
$.fn.photocols.defaults.animationSpeed = 2;

TypeScript

TypeScript definitions are included. Import types if needed:

import { PhotocolsOptions, PhotocolsItem } from 'jquery.photocols';

const options: PhotocolsOptions = {
  height: 500,
  data: [
    { title: 'Test', subtitle: 'Sub', url: '#', img: 'test.jpg' }
  ]
};

$('#gallery').photocols(options);

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Requires jQuery 1.7 or higher.

Development

# Install dependencies
npm install

# Build minified version
npm run build

Changelog

v2.0.0

• Breaking: Requires ES6-compatible browser (or transpilation)
• Security: Fixed XSS vulnerability in title/subtitle rendering
• Performance: Replaced setTimeout with requestAnimationFrame
• Performance: Uses CSS transforms for GPU-accelerated animation
• Performance: Added resize debouncing
• Feature: Multiple instance support
• Feature: Added pause(), resume(), refresh(), destroy() methods
• Feature: TypeScript definitions included
• Feature: New configurable options: titleTop, subtitleTop, maskHeight, animationSpeed, debounceDelay
• Feature: Scroll direction support (up, down, left, right)
• Feature: Variable speed per column/row for parallax effects
• Feature: Pause entire gallery on hover option
• Feature: Lazy loading with IntersectionObserver
• Feature: New options: direction, variableSpeed, speedVariation, pauseAllOnHover, lazyLoad, lazyLoadThreshold, placeholderColor
• Fix: Global variable leak
• Fix: Memory leak on resize/destroy
• Fix: CSS text-transformation typo (now text-transform)
• Build: Migrated from Grunt to npm scripts with Terser

v1.0.3

• Initial stable release

License

MIT License - see LICENSE for details.