Responsive Photo Gallery with Smart Row Layout – Lumosaic

Lumosaic is a lightweight, responsive photo gallery library that automatically arranges photos of varying orientations into perfectly aligned rows spanning full container width.

It calculates image dimensions and distributes them intelligently to create a balanced, responsive gallery layout that preserves the original aspect ratios of your images.

Features:

• Intelligent Row Algorithm:
  Calculates optimal image placement to create perfectly aligned rows that fill container width.
• Automatic Dimension Detection: Retrieves width and height from PNG, JPEG, and WebP files by reading binary headers.
• Responsive Breakpoints: Adjusts row heights automatically for mobile, tablet, and desktop screen sizes.
• Flexible Data Input: Accepts image objects with dimensions, URL arrays, or existing DOM elements.
• Built-in Shuffle Function: Randomizes image order with a single method call.
• Video Support: Displays play button overlays on video cover images.

How To Use It:

1. Download the package and load Lumosaic’s JavaScript & CSS files in the document.

<link rel="stylesheet" href="/lumosaic.css" />
<script src="/lumosaic.js"></script>

2. Create a container element for your photo gallery.

<div id="gallery-container"></div>

3. Initialize the gallery with an array of image objects:

const images = [
  { 
    src: "1.jpg", 
    width: 800, 
    height: 600 
  },
  { 
    src: "2.jpg", 
    width: 600, 
    height: 800 
  },
  { 
    src: "3.jpg", 
    width: 800, 
    height: 800 
  },
  // more images here
];

// Initialize Lumosaic on the container element
new Lumosaic("gallery-container", images).init();

4. You can also pass an array of image URLs. Lumosaic will automatically detect dimensions:

// Simple URL array
const imageUrls = [
  "/path/to/1.jpg",
  "/path/to/2.jpg",
  "/path/to/3.jpg",
];

// Enable automatic dimension retrieval
new Lumosaic("gallery-container", imageUrls).init({
    shouldRetrieveWidthAndHeight: true
});

5. You can convert existing HTML image elements into a Lumosaic gallery:

<div id="source-images">
  <img src="1.jpg" />
  <img src="2.jpg" />
  <img src="3.jpg" />
</div>
<div id="gallery-container"></div>

// Pass the ID of the source container
// The source element will be removed after processing
new Lumosaic("gallery-container", "source-images").init();

6. Use the following data attributes for more control:

<div id="source-images">
  <img 
    data-src="full-resolution.jpg" 
    data-preview="thumbnail.jpg" 
    data-width="1920" 
    data-height="1080" 
  />
</div>

7. All configuration options.

• rowHeightSM (float): Height-to-width ratio for mobile devices (screen width < 768px). Default is 0.25.
• rowHeightMD (float): Height-to-width ratio for tablets (screen width ≥ 768px and < 1024px). Default is 0.2.
• rowHeightXL (float): Height-to-width ratio for desktops (screen width ≥ 1024px). Default is 0.18.
• rowHeight (float): Overrides all breakpoint-specific ratios with a single value. Default is none.
• shouldRetrieveWidthAndHeight (boolean): Automatically fetches image dimensions from file headers when width and height are not provided. Default is false.
• fallbackImageWidth (integer): Width in pixels used when dimension retrieval fails. Default is 1000.
• fallbackImageHeight (integer): Height in pixels used when dimension retrieval fails. Default is 1000.
• maxImageRatio (float): Maximum width-to-height ratio allowed. Images exceeding this limit will have their width adjusted. Default is 1.6.
• minImageRatio (float): Minimum width-to-height ratio allowed. Images below this limit will have their width adjusted. Default is 0.65.
• maxRows (integer): Maximum number of rows to display. Set to 0 for unlimited rows. Default is 0.
• stretchLastRow (boolean): Stretches the final row to fill container width by redistributing images from previous rows. Default is true.
• shuffleImages (boolean): Randomizes image order before rendering. Default is false.
• gap (integer): Spacing in pixels between images horizontally and between rows vertically. Default is 4.
• playButtonOnVideoCover (boolean): Displays a play button overlay on video cover images. Default is true.
• observeWindowWidth (boolean): Triggers gallery re-render when window or container width changes. Default is false.

new Lumosaic("gallery-container", "source-images").init({
  rowHeightSM: 0.25,
  rowHeightMD: 0.2,
  rowHeightXL: 0.18,
  shouldRetrieveWidthAndHeight: false,
  fallbackImageWidth: 1000,
  fallbackImageHeight: 1000,
  maxImageRatio: 1.6,
  minImageRatio: 0.65,
  maxRows: 0,
  stretchLastRow: true,
  shuffleImages: false,
  gap: 4,
  playButtonOnVideoCover: true,
  observeWindowWidth: true
});

8. API methods.

// Initialize the gallery and store the instance
const gallery = new Lumosaic("gallery-container", images).init({
  maxRows: 3,
  gap: 10
});

// Shuffle all images and re-render the gallery
gallery.shuffleImages();

// Replace the entire image collection
// Accepts the same data types as the constructor
const newImages = [
  { src: "new-image-1.jpg", width: 800, height: 600 },
  { src: "new-image-2.jpg", width: 600, height: 800 }
];
gallery.replaceImages(newImages);

// Update configuration options
// The gallery will re-render with new settings
gallery.updateOptions({
  gap: 20,
  maxRows: 5,
  rowHeight: 0.15
});

// Destroy the gallery instance
// Removes all DOM elements and disconnects observers
gallery.destroy();

9. Lumosaic works directly with the Obsidium lightbox. Initialize Obsidium after Lumosaic completes rendering:

const images = [
  { src: "1.jpg", width: 800, height: 600 },
  { src: "2.jpg", width: 800, height: 600 },
  { src: "3.jpg", width: 800, height: 800 },
];
// Initialize Lumosaic, then bind Obsidium
const lumosaic = new Lumosaic("gallery-container", images).init().then(() => {
  // Obsidium binds to the rendered gallery
  new Obsidium("#gallery-container").init();
});

FAQs:

Q: Can Lumosaic handle images loaded dynamically after page load?
A: Yes. Call the replaceImages() method with the new image array. Lumosaic will process the new images and re-render the gallery.

Q: How does Lumosaic perform with large image collections?
A: The library uses DocumentFragment for rendering to minimize reflows. For galleries with hundreds of images, set maxRows to limit the initial render.

Q: Can I use Lumosaic with images from different domains?
A: Yes, but automatic dimension detection requires CORS headers from the image server. If the server doesn’t send proper CORS headers, the fetch will fail and Lumosaic will use fallback dimensions.

The post Responsive Photo Gallery with Smart Row Layout – Lumosaic appeared first on CSS Script.