Responsive Mosaic Photo Gallery / Grid Plugin For jQuery - mosaic.js

File Size: 188 KB
Views Total: 21593
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
Responsive Mosaic Photo Gallery / Grid Plugin For jQuery - mosaic.js

mosaic.js is an easy and responsive jQuery image galery / grid plugin that dynamically arranges a group of images into a mosaic style grid while preserving the original aspect ratios. Similar to the Flick / Google plus / Masonry grid layouts.

How to use it:

1. Put the required CSS file jquery.mosaic.css in the head section of the html page.

<link href="jquery.mosaic.css" rel="stylesheet">

2. Insert a collection of images into the container as follows. The data-high-res-image-src is used to specify the path to the high resolution image when the gallery is running on the desktop.

<div id="mosaic" class="mosaic">
  <img src="1.jpg" data-high-res-image-src="high-1.jpg">
  <img src="2.jpg" data-high-res-image-src="high-2.jpg">
  <img src="3.jpg" data-high-res-image-src="high-3.jpg">
  <img src="4.jpg" data-high-res-image-src="high-4.jpg">
  <img src="5.jpg" data-high-res-image-src="high-5.jpg">

3. Put the jQuery mosaic.js script after jQuery library but before you close the body tag.

<script src="//"></script>
<script src="jquery.mosaic.js"></script>

4. Just call the plugin and you're done.


5. Set the maximum desired height of rows.

  maxRowHeight: 400

6. Define whether to rebuild the mosaic when the window is resized or not.

  refitOnResize: true

7. Specify the aspect ratio to use when none has been specified, or can't be calculated.

  defaultAspectRatio: 1

8. 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 the items respecting their aspect ratio but surpassing the specified maxRowHeight.

  maxRowHeightPolicy: 'oversize'

9. The default highResImagesWidthThreshold option. When set to a width, item <div>s or <a>s or <img>s wider than this will be given a higher resolution background image (if specified on html div property data-high-res-background-image-url) or image src (if specified on html img property data-high-res-image-src).

  highResImagesWidthThreshold: 350

10. The time in 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.

  refitOnResizeDelay: false,

11. Specify the margin size in pixels for the outer edge of the whole mosaic

  outerMargin: 0

12. Specify the gap size in pixels to leave a space between elements.

  innerGap: 0

13. 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.

  maxRows: false

14. Specify 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.

  responsiveWidthThreshold: false

15. Specify the amount of items will be shown when the responsiveWidthThreshold is met.

  maxItemsToShowWhenResponsiveThresholdSurpassed: false

16. 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.

  showTailWhenNotEnoughItemsForEvenOneRow: false


v0.15.3 (2018-12-11)

  • Solved CSS bug for newly added video element support.


  • Mosaic is not resized when hidden, support for VIDEO elements. 


  • Solved bug with high res images
  • New options maxItemsToShowWhenResponsiveThresholdSurpassed and showTailWhenNotEnoughItemsForEvenOneRow


  • Added maxRows option. 


  • Width and height getters and setters standardized to .width() and .height() methods


  • Width and height getters and setters standardized to .width() and .height() methods


  • Feature : pass mosaic params as data-* attributes
  • Reformatting spaces to tabs


  • New maxRowHeightPolicy 'tail'


  • Solved bug that actually wasn't there


  • Version 0.12, now allows to specify a margin for the mosaic, and a gap size for between elements

This awesome jQuery plugin is developed by tin-cat. For more Advanced Usages, please check the demo page or visit the official website.