Lumosaic

Adaptive photo gallery with intelligent row layout

Download Get Started View on GitHub
SHUFFLE

Get started

Download the latest release from the releases page and include the files in your project:

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

Create a container element:

<div id="lumosaic"></div>

Initialize the gallery:

const images = [
    { src: "https://picsum.photos/800/600?random=1", width: 800, height: 600 },
    { src: "https://picsum.photos/800/600?random=2", width: 800, height: 600 },
    { src: "https://picsum.photos/800/800?random=3", width: 800, height: 800 },
    { src: "https://picsum.photos/600/800?random=4", width: 600, height: 800 },
    { src: "https://picsum.photos/800/600?random=5", width: 800, height: 600 },
    { src: "https://picsum.photos/800/800?random=6", width: 800, height: 800 },
]

new Lumosaic("lumosaic", images).init()

That's it! Your gallery is ready.

Usage

Array of objects

Using an array of image objects with specified width and height.

const images = [
    { src: "https://picsum.photos/800/600?random=1", width: 800, height: 600 },
    { src: "https://picsum.photos/800/600?random=2", width: 800, height: 600 },
    { src: "https://picsum.photos/800/800?random=3", width: 800, height: 800 },
    { src: "https://picsum.photos/600/800?random=4", width: 600, height: 800 },
    { src: "https://picsum.photos/800/600?random=5", width: 800, height: 600 },
    { src: "https://picsum.photos/800/800?random=6", width: 800, height: 800 },
]

new Lumosaic("lumosaic", images).init()

Array of string

Using an array of image URLs. Width and height will be calculated automatically if the shouldRetrieveWidthAndHeight option is set to true.

const images = [
    "https://picsum.photos/800/600?random=1",
    "https://picsum.photos/800/600?random=2",
    "https://picsum.photos/800/800?random=3",
    "https://picsum.photos/600/800?random=4",
    "https://picsum.photos/800/600?random=5",
    "https://picsum.photos/800/800?random=6",
]

new Lumosaic("lumosaic", images).init()

Replace existing images

Using existing images from the #images element.
Data attributes data-src, data-preview, data-width, and data-height can also be used.
The #images element will be removed from the DOM.

<div id="images">
    <img src="https://picsum.photos/800/600?random=1" />
    <img src="https://picsum.photos/800/600?random=2" />
    <img src="https://picsum.photos/800/800?random=3" />
    <img src="https://picsum.photos/600/800?random=4" />
    <img src="https://picsum.photos/800/600?random=5" />
    <img src="https://picsum.photos/800/800?random=6" />
</div>

<div id="lumosaic"></div>
new Lumosaic("lumosaic", "images").init()

Passing options

You can pass additional options to the init method to customize the gallery.

new Lumosaic("lumosaic", images).init({
    maxRows: 2,
    gap: 10
})

Preview

See Lumosaic in action

rowHeight
maxRows
stretchLastRow
gap
maxImageRatio
minImageRatio

Options

Row Height Options

rowHeightSM
Default: 0.25 (float)
Height/width desired row ratio for mobile devices (screen width < 768px)
rowHeightMD
Default: 0.2 (float)
Height/width desired row ratio for medium devices (screen width >= 768px and < 1024px)
rowHeightXL
Default: 0.18 (float)
Height/width desired row ratio for extra large devices (screen width >= 1024px)
rowHeight
Default: none (float)
Height/width desired row ratio for all screen sizes (overwrites SM, MD and XL options)

Image Options

shouldRetrieveWidthAndHeight
Default: false (boolean)
If true, automatically retrieves image dimensions from the image file when width and height are not provided
fallbackImageWidth
Default: 1000 (integer)
Fallback width in pixels used when image dimensions cannot be retrieved
fallbackImageHeight
Default: 1000 (integer)
Fallback height in pixels used when image dimensions cannot be retrieved
maxImageRatio
Default: 1.6 (float)
Maximum width/height ratio allowed for images. Images exceeding this ratio will have their width adjusted to fit within the limit
minImageRatio
Default: 0.65 (float)
Minimum width/height ratio allowed for images. Images below this ratio will have their width adjusted to fit within the limit

Layout Options

maxRows
Default: 0 (integer)
Maximum number of rows to display. Set to 0 for no limit
stretchLastRow
Default: true (boolean)
If true, stretches the last row to fill the container by redistributing images from previous rows if needed
shuffleImages
Default: false (boolean)
If true, shuffles images randomly before rendering the gallery
gap
Default: 4 (integer)
Gap in pixels between images (horizontal) and between rows (vertical)
playButtonOnVideoCover
Default: true (boolean)
If true, shows play button on video cover
observeWindowWidth
Default: true (boolean)
Gallery re-render in response to window or gallery width changes

Methods

init(options)
Params: options (object, optional)
Initializes the gallery with the given options
shuffleImages()
Params: none
Shuffles the images in the gallery
replaceImages(images)
Params: images (array)
Replaces the images in the gallery with the given images
updateOptions(options)
Params: options (object)
Updates the gallery configuration with the given options and re-renders the gallery.
destroy()
Params: none
Destroys the gallery and removes it from the DOM.