A lightweight vanilla JavaScript plugin for creating fluid galleries as seen on Flickr and Google Images.

Download   View on GitHub

Overview and Features

Released under the MIT License. Source on Github (changelog). Tested in Firefox, Safari, Chrome, Opera, Internet Explorer 8+. No dependencies, written in plain JavaScript.

This plugin was developed by and for Pixabay.com - an international repository for free Public Domain images. We have implemented this plugin in production and we share this piece of software - in the spirit of Pixabay - freely with others.

Live Demo


Include the stylesheet flex-images.css in the <head> section of your HTML document - and the JavaScript file flex-images.min.js before the closing </body> tag. flexImages accepts settings from an object of key/value pairs.

new flexImages({ key1: value1, key2: value2 });

To update any settings or to reload modified content, simply re-initialize flexImages again on the appropriate container. The plugin automatically prevents multiple bindings to one and the same element. This may be used for content that gets modified later on via AJAX.


selectorstring or DOM elementRequired selector for container or DOM element that holds the individual images/objects.
container'.item'Selector of the individual image/object containers.
object'img'Selector of the image/object inside a container.
rowHeight180Maximum height of a row.
maxRowsnullMaximum number of rows to display. Images/Objects exceeding this row are hidden.
truncatefalseHide incomplete last row of images/objects.

Example Code

HTML Markup

<div class="flex-images">
    <div class="item" data-w="219" data-h="180"><img src="images/1.jpg"></div>
    <div class="item" data-w="279" data-h="180"><img src="images/2.jpg"></div>
    <div class="item" data-w="270" data-h="180"><img src="images/3.jpg"></div>
    <div class="item" data-w="270" data-h="180"><img src="images/4.jpg"></div>
    <div class="item" data-w="147" data-h="180"><img src="images/5.jpg"></div>
    <div class="item" data-w="276" data-h="180"><img src="images/6.jpg"></div>
    <div class="item" data-w="319" data-h="180"><img src="images/7.jpg"></div>
    <div class="item" data-w="270" data-h="180"><img src="images/8.jpg"></div>
    <div class="item" data-w="240" data-h="180"><img src="images/9.jpg"></div>
    <div class="item" data-w="270" data-h="180"><img src="images/10.jpg"></div>
    <div class="item" data-w="240" data-h="180"><img src="images/11.jpg"></div>
    <div class="item" data-w="270" data-h="180"><img src="images/12.jpg"></div>
    <div class="item" data-w="283" data-h="180"><img src="images/13.jpg"></div>
    <div class="item" data-w="271" data-h="180"><img src="images/14.jpg"></div>
    <div class="item" data-w="258" data-h="180"><img src="images/15.jpg"></div>

Each image must be wrapped inside a container element. The container must have a width (data-w) and height (data-h) attribute set that corresponds to the image's/object's original dimension.

JavaScript code

new flexImages({ selector: '.flex-images', rowHeight: 140 });

How it works: The plugin dynamically changes the width and height of all containers. The images themselves have their height and width set to 100%. Thus, each image takes up the full space inside its container.

This architecture enables a very flexible grid layout that works with more than just images. E.g. objects may be placed on top of the images via absolute positioning. Or instead of images, the containers may be filled with videos or even plain text.

More Examples

Please take a look at the source code of this page to see how these demos work.

1. Fixed number of two complete rows with lazy loading of images; only images that are actually visible are retrieved from the server:

For lazy loading of images or iframes, it's required to use a "blank.gif" pixel as the source of all images. The actual source URL must be given in a data-src attribute of the image. On init, the plugin will replace the dummy src attribute (blank.gif) with the actual source URL for all visible images.

2. A fluid grid with video content and only full rows:

3. Showing a title underneath + less margin between images:

Caption 1
Caption 2
Caption 3
Caption 4
Caption 5

4. Overlaying caption - could be a link or a button, as well:

Caption 1
Caption 2
Caption 3
Caption 4
Caption 5

5. Cut off parts of the images, e.g. a Shutterstock ID:

Original (uncut) first image with Shutterstock ID at the bottom:

This plugin is used in production on Pixabay.com, where you can see flexImages at work in various locations and with all available options. Please report any bugs and issues at the GitHub repositiory.

This software is released as Open Source under the MIT License by Simon Steinberger / Pixabay.com.

About Us Blog More Goodies © Pixabay.com / Simon Steinberger / Hans Braxmeier