Key features

Pixel perfect seamless mosaics
Obviously responsive
Create mosaics of images or divs containing whatever your want
Automatically loads high resolution images for retina glory

Basic usage

Download the jQuery Mosaic plugin
Include the jQuery library and the jquery.mosaic.js + jquery.mosaic.css files from the jQuery Mosaic download in your head section. <html> <head> ... <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script> <script type="text/javascript" src="jquery.mosaic.js"></script> <link rel="stylesheet" type="text/css" href="jquery.mosaic.css" /> ... </head> <body> ...
Create a DIV with an id and place your contents inside. Each DIV, A or IMG you place there will be considered as a piece of the mosaic. <div id="myMosaic"> <img src="image1.jpg" width="400" height="350" /> <img src="image2.jpg" width="320" height="200" /> <img src="image3.jpg" width="870" height="420" /> <img src="image4.jpg" width="442" height="922" /> ... </div>
Build the mosaic by running the plugin in your div <script> $('#myMosaic').Mosaic(); </script>
That's it! See the examples and their source code to learn more.

Options

You can optionally specify the following options when calling the plugin to customize the mosaic:

maxRowHeight

The maximum desired height of rows

400
refitOnResize

Whether to rebuild the mosaic when the window is resized or not

true
refitOnResizeDelay

Milliseconds to wait after a resize event to refit the mosaic. Useful when creating huge mosaics that can take some CPU time on the user's browser. Leave it to false to refit the mosaic in realtime

false
defaultAspectRatio

The aspect ratio to use when none has been specified, or can't be calculated

1
maxRowHeightPolicy
Sometimes some of the remaining items cannot be fitted on a row without surpassing the maxRowHeight. For those cases, choose one of the available settings for maxRowHeightPolicy:
- skip Does not renders the unfitting items.
- crop Caps the desired height to the specified maxRowHeight, resulting in those items not keeping their aspect ratios.
- oversize Renders items respecting their aspect ratio but surpassing the specified maxRowHeight.
- tail Renders items respecting their aspect ratio without surpassing the specified maxRowHeight, resulting in a last row that might not completely fit the screen horizontally.
skip
maxRows

In some scenarios you might need fine control about the maximum number of rows of the mosaic. If specified, the mosaic won't have more than this number of rows. If responsiveWidthThreshold is specified, maxRows are not considered when the threshold has been reached

false
highResImagesWidthThreshold

The item width on which to start using the the provided high resolution image instead of the normal one. High resolution images are specified via the "data-high-res-image-src" or "data-high-res-background-image-url" html element properties of each item.

350
outerMargin

A margin size in pixels for the outher edge of the whole mosaic.

0
innerGap

A gap size in pixels to leave a space between elements.

0
responsiveWidthThreshold

The minimum width for which to keep building the mosaic. If specified, when the width is less than this, the mosaic building logic is not applied, and one item per row is always shown. This might help you avoid resulting item sizes that are too small and might break complex html/css inside them, specially when aiming for great responsive mosaics. When using this, you can also specify a "data-only-force-height-when-necessary" html item property with value "1" in the specific items you don't want to apply forced aspect ratios when this minimum width threshold is reached.

false
maxItemsToShowWhenResponsiveThresholdSurpassed

If set (and also responsiveWidthThreshold is set), only this amount of items will be shown when the responsiveWidthThreshold is met.

false
showTailWhenNotEnoughItemsForEvenOneRow

If this is set to true, when there are not enough items to fill even a single row, they will be shown anyway even if they do not complete the row horizontally. If left to false, no mosaic will be shown in such occasions.

false

For example:

<div id="myMosaic">
    <img src="image1.jpg" />
    <img src="image2.jpg" />
    <img src="image3.jpg" />
    <img src="image4.jpg" />
    ...
</div>

$('#myMosaic').Mosaic({
    maxRowHeight: 800,
    refitOnResize: true,
    refitOnResizeDelay: false,
    defaultAspectRatio: 0.5,
    maxRowHeightPolicy: 'crop',
    highResImagesWidthThreshold: 850,
    responsiveWidthThreshold: 500
});

Advanced usage

Instead of passing options in the Javascript plugin call, you can pass them right into the HTML element by adding data-* attributes <div id="myMosaic" data-max-row-height="800" data-refit-on-resize="1" data-refit-on-resize-relay="0" data-default-aspect-ratio="0.5" data-max-row-height-policy="crop" data-high-res-images-width-threshold="850" data-responsive-width-threshold="500"> <img src="image1.jpg" /> <img src="image2.jpg" /> <img src="image3.jpg" /> <img src="image4.jpg" /> ... </div> $('#myMosaic').Mosaic();
You can specify the aspect ratio of each mosaic piece by adding the data-aspect-ratio property on each element instead of the height and width <div id="myMosaic"> <img src="image1.jpg" data-aspect-ratio="1.432" /> <img src="image2.jpg" data-aspect-ratio="0.3" /> <img src="image3.jpg" data-aspect-ratio="1.4842" /> <img src="image4.jpg" data-aspect-ratio="0.883" /> ... </div>
You can specify a high resolution version of the image by adding the data-high-res-image-src property on each element. It will only be loaded and used when needed <div id="myMosaic"> <img src="image1.jpg" data-aspect-ratio="1.432" data-high-res-image-src="image1_highres.jpg"/> <img src="image2.jpg" data-aspect-ratio="0.3" data-high-res-image-src="image2_highres.jpg" /> <img src="image3.jpg" data-aspect-ratio="1.4842" data-high-res-image-src="image3_highres.jpg" /> <img src="image4.jpg" data-aspect-ratio="0.883" data-high-res-image-src="image4_highres.jpg" /> ... </div>
You can use DIVs instead of IMGs for the mosaic. They will be resized to the proper width and height, and their contents will be left untouched, like in this example <div id="myMosaic"> <div data-aspect-ratio="1.32">My content</div> <div data-aspect-ratio="1.02">My content</div> <div data-aspect-ratio="0.8">My content</div> <div data-aspect-ratio="1.02">My content</div> ... </div>
You can set background images to DIVs for more interesting creative options, add the provided item CSS class to each mosaic element to do so, or use your own CSS <div id="myMosaic"> <div class="item withImage" data-aspect-ratio="1.32" style="background-image: url('image1.jpg');">My content</div> <div class="item withImage" data-aspect-ratio="1.02" style="background-image: url('image2.jpg');">My content</div> <div class="item withImage" data-aspect-ratio="0.8" style="background-image: url('image3.jpg');">My content</div> <div class="item withImage" data-aspect-ratio="1.02" style="background-image: url('image4.jpg');">My content</div> ... </div>
When using background images on DIVs, you can still specify a high resolution background image by adding the high-res-background-image-url property <div id="myMosaic"> <div class="item withImage" data-aspect-ratio="1.32" style="background-image: url('image1.jpg');" data-high-res-background-image-url="image1_highres.jpg">My content</div> <div class="item withImage" data-aspect-ratio="1.02" style="background-image: url('image2.jpg');" data-high-res-background-image-url="image2_highres.jpg">My content</div> <div class="item withImage" data-aspect-ratio="0.8" style="background-image: url('image3.jpg');" data-high-res-background-image-url="image3_highres.jpg">My content</div> <div class="item withImage" data-aspect-ratio="1.02" style="background-image: url('image4.jpg');" data-high-res-background-image-url="image4_highres.jpg">My content</div> ... </div>
Using Anchors instead of DIVs, background images, and an overlay you can create a neat interactive mosaic. <div id="myMosaic"> <div class="item withImage" data-aspect-ratio="1.32" style="background-image: url('image1.jpg');" data-high-res-background-image-url="image1_highres.jpg"> <div class="overlay"><div class="texts"> <h1>Title</h1> <h1>Subtitle</h1> </div></div> </div> <div class="item withImage" data-aspect-ratio="1.02" style="background-image: url('image2.jpg');" data-high-res-background-image-url="image2_highres.jpg"> <div class="overlay"><div class="texts"> <h1>Title</h1> <h1>Subtitle</h1> </div></div> </div> <div class="item withImage" data-aspect-ratio="0.8" style="background-image: url('image3.jpg');" data-high-res-background-image-url="image3_highres.jpg"> <div class="overlay"><div class="texts"> <h1>Title</h1> <h1>Subtitle</h1> </div></div> </div> .. </div>

Basic example images mosaicThe most simple implementation, just a few lines of code to see how it works.
Creating a mosaic of divs instead of imagesYou can create mosaic of anything that can be contained within a div. This is an example.
A mosaic of linkable images with additional information when hoveringA more useable example to create mosaics of images you can interact with.
High resolution images examplejQuery Mosaic can switch to a higher resolution file when needed to keep images crisp.
Example with marginsYou can specify an outer margin for the whole mosaic and an inner gap to leave an empty space between mosaic items independently.
maxRowHeightPolicy demoSee the differences between the maxRowHeightPolicy modes
See a real applicationSee the plugin at work at Litmind.com

Version history

v0.15.2
Added maxRows option for those situations where you need fine control on the maximum number of rows of your mosaic. Added advanced options maxItemsToShowWhenResponsiveThresholdSurpassed and showTailWhenNotEnoughItemsForEvenOneRow for even more fine-grained control of your mosaic.
v0.15
Added the ability to pass parameters as html data-* attributes. Solved floating point width bug for compatibility with jQuery versions < 3. Thanks to @BenTalagan
v0.14
New maxRowHeightPolicy 'tail' that renders items respecting their aspect ratio without surpassing the specified maxRowHeight, resulting in a last row that might not completely fit the screen horizontally, suggested by @borekl and @nzjrs
v0.13
New outerMargin and innerGap parameters.

jQuery Mosaic

with
by tin.cat · download on Github · see examples

A jQuery plugin for building responsive mosaics of images or any other content fitted to match heights in multiple rows while maintaining aspect ratios

Key features

Basic usage

Options

Advanced usage

Version history