Masonry Image Gallery
Masonry Layout - Cascading Grid Layout
Masonry is a JavaScript grid layout library that works by placing elements in optimal position based on available vertical space, creating a beautiful cascading grid effect. Perfect for image galleries, portfolios, and content grids.
warning
Important: When using Masonry with images, you MUST wait for all images to load before initializing Masonry. Otherwise, the grid will have incorrect heights and overlapping issues. This is why we use the
imagesLoaded plugin automatically.Basic Image Gallery
A simple masonry grid with images of varying heights:
HTML Structure:
<div class="grid" id="masonry-basic">
<!-- Grid sizer for column width -->
<div class="grid-sizer"></div>
<!-- Grid items -->
<div class="grid-item">
<img src="image1.jpg" class="img-fluid rounded" alt="Image 1">
</div>
<div class="grid-item">
<img src="image2.jpg" class="img-fluid rounded" alt="Image 2">
</div>
</div>JavaScript Initialization (with imagesLoaded):
// Using our helper function (includes imagesLoaded automatically)
window.masonryBasic = window.initMasonry('#masonry-basic', {
itemSelector: '.grid-item',
columnWidth: '.grid-sizer',
percentPosition: true,
gutter: 15
});Advanced Gallery - Mixed Sizes
Masonry grid with items of different widths using Bootstrap grid classes:
Key Features
- Smart Positioning: Automatically finds optimal layout
- Responsive: Adapts to different screen sizes
- Flexible: Works with any content (images, cards, etc.)
- Percentages: Column width based on container size
- No Dependencies: Pure JavaScript (works with or without jQuery)
- Lightweight: Small file size, fast performance
- Image Support: Integrated with imagesLoaded plugin
Best Practices
- Always use imagesLoaded: Wait for images to load before initializing Masonry
- Use a grid-sizer: Helps Masonry calculate column widths
- Set percentPosition: true: Makes the grid responsive
- Define gutter: Add spacing between items
- Call layout(): After dynamic content changes
- Combine with Lightbox: Great for image galleries
Masonry Options
| Option | Type | Default | Description |
|---|---|---|---|
itemSelector
|
String | '.grid-item'
|
Selector for grid items |
columnWidth
|
String/Number | '.grid-sizer'
|
Column width (selector or pixels) |
percentPosition
|
Boolean | true
|
Use percentages for positioning (responsive) |
gutter
|
Number | 15
|
Space between items (pixels) |
horizontalOrder
|
Boolean | false
|
Lay out items to maintain horizontal left-to-right order |
fitWidth
|
Boolean | false
|
Sets container width to fit available columns |
Implementation Notes
Installation
Masonry is already included in UltraViolet via CDN and npm:
<!-- CDN (in cdn-scripts.blade.php) -->
<script src="https://cdn.jsdelivr.net/npm/masonry-layout@4.2.2/dist/masonry.pkgd.min.js"></script>
<!-- NPM (already imported in admin-static.js) -->
import Masonry from 'masonry-layout'
import imagesLoaded from 'imagesloaded'Why imagesLoaded is Critical
When Masonry initializes, it needs to know the height of each item to position them correctly. If images haven't loaded yet, their height is 0, causing overlapping and incorrect layouts. The imagesLoaded plugin solves this by waiting for all images to load before calculating positions.
// ❌ BAD - Without imagesLoaded (images will overlap!)
const msnry = new Masonry('.grid', {
itemSelector: '.grid-item'
});
// ✅ GOOD - With imagesLoaded (proper layout)
const msnry = new Masonry('.grid', {
itemSelector: '.grid-item'
});
imagesLoaded('.grid', function() {
msnry.layout();
});
// ✅ BEST - Use our helper function (includes imagesLoaded)
window.initMasonry('.grid', {
itemSelector: '.grid-item'
});Helper Functions
UltraViolet provides convenient helper functions in admin-static.js:
window.initMasonry(container, options)- Initialize with imagesLoaded supportwindow.destroyMasonry(instance)- Clean up a Masonry instance
check_circle
Pro Tip: Combine Masonry with the Lightbox plugin for beautiful image galleries with full-screen preview capabilities!