Masonry Style Gallery Plugin FAQs

Basic Functionality & Layout Issues

Q: Why isn't the masonry layout applying to my galleries? A: Complete troubleshooting checklist:

1. Plugin files uploaded - Both CSS and JS to file manager

2. Code injection correct - Header section with proper syntax

3. Gallery type compatible - Works best with grid/masonry galleries

4. JavaScript loading - Check browser console for errors

5. Cache cleared - Test in incognito mode

Basic setup:

html

<!-- Masonry Style Gallery Plugin -->
<link href="/s/plugin-masonry-gallery.css" rel="stylesheet">
<script src="/s/plugin-masonry-gallery.js"></script>
<script>
pluginMasonryGallery({
    'galleryIDs': 'auto', // Apply to all galleries
    'ignoreGalleryIDs': 'off'
});
</script>
<!-- end Masonry Style Gallery Plugin -->

Q: Why do images overlap or layout breaks in masonry view? A: Common layout issues and fixes:

Issue 1: Images not fully loaded

css

.masonry-gallery {
    opacity: 0;
    transition: opacity 0.3s ease;
}

.masonry-gallery.loaded {
    opacity: 1;
}

Issue 2: Container sizing problems

css

.masonry-gallery {
    width: 100% !important;
    height: auto !important;
    overflow: visible !important;
}

.masonry-gallery .gallery-item {
    break-inside: avoid !important;
    page-break-inside: avoid !important;
    margin-bottom: 20px !important;
}

Issue 3: Image sizing conflicts

css

.masonry-gallery img {
    width: 100% !important;
    height: auto !important;
    display: block !important;
    max-width: none !important;
}

Targeting & Configuration

Q: How do I apply masonry style to only specific galleries? A: Method 1: Target by gallery block ID

javascript

pluginMasonryGallery({
    'galleryIDs': '#block-yui_3_17_2_1_1234567890_12345,#block-yui_3_17_2_1_1234567890_67890',
    'ignoreGalleryIDs': 'on'
});

Method 2: Use CSS classes

html

<!-- Add class to specific gallery sections -->
<div class="masonry-enabled">
    <!-- Gallery content here -->
</div>

javascript

pluginMasonryGallery({
    'selector': '.masonry-enabled .sqs-gallery',
    'autoDetect': false
});

Q: Can I exclude certain galleries (like Instagram blocks) from the masonry effect? A: Yes, use exclusion settings:

javascript

pluginMasonryGallery({
    'ignoreGalleryIDs': '#block-instagram-feed,#block-logo-gallery,#block-team-photos',
    'excludeClasses': ['instagram-feed', 'logo-gallery'],
    'galleryIDs': 'auto'
});

Common galleries to exclude:

• Instagram feed blocks

• Logo/client galleries where order matters

• Team photo galleries

• Before/after comparison galleries

Customization & Styling

Q: How do I adjust the spacing between masonry gallery items? A: Spacing control options:

Method 1: CSS gaps

css

.masonry-gallery {
    column-gap: 20px !important;
    margin-bottom: 20px !important;
}

.masonry-gallery .gallery-item {
    margin-bottom: 20px !important;
    break-inside: avoid !important;
}

Method 2: Plugin configuration

javascript

pluginMasonryGallery({
    'gutter': 20, // 20px spacing
    'gutterHorizontal': 20,
    'gutterVertical': 20
});

Method 3: Custom spacing by screen size

css

/* Desktop spacing */
@media screen and (min-width: 768px) {
    .masonry-gallery {
        column-gap: 30px !important;
    }
    .masonry-gallery .gallery-item {
        margin-bottom: 30px !important;
    }
}

/* Mobile spacing */
@media screen and (max-width: 767px) {
    .masonry-gallery {
        column-gap: 15px !important;
    }
    .masonry-gallery .gallery-item {
        margin-bottom: 15px !important;
    }
}

Q: Can I control the number of columns in the masonry layout? A: Column control methods:

Method 1: CSS columns

css

.masonry-gallery {
    column-count: 3 !important; /* Desktop: 3 columns */
}

@media screen and (max-width: 1024px) {
    .masonry-gallery {
        column-count: 2 !important; /* Tablet: 2 columns */
    }
}

@media screen and (max-width: 767px) {
    .masonry-gallery {
        column-count: 1 !important; /* Mobile: 1 column */
    }
}

Method 2: Plugin configuration

javascript

pluginMasonryGallery({
    'columns': {
        'desktop': 3,
        'tablet': 2,
        'mobile': 1
    },
    'breakpoints': {
        'tablet': 1024,
        'mobile': 768
    }
});

Method 3: Flexible width-based columns

css

.masonry-gallery {
    column-width: 300px !important; /* Columns will auto-adjust based on width */
    column-gap: 20px !important;
}

Gallery Types & Compatibility

Q: Does the masonry layout work with all Squarespace gallery types? A: Compatibility by gallery type:

• ✅ Grid galleries - Full support, best results

• ✅ Masonry galleries - Enhanced masonry effect

• ✅ Simple list galleries - Good support

• ⚠️ Slideshow galleries - Not recommended (breaks navigation)

• ❌ Carousel galleries - Incompatible

• ❌ Banner galleries - Layout conflicts

Recommended gallery settings for best masonry results:

1. Use Grid or Masonry gallery design

2. Set Aspect Ratio to "Auto" or "Original"

3. Enable Image Metadata if needed

4. Disable Auto Crop for natural image proportions

Q: Why does my masonry gallery layout break on mobile? A: Mobile responsive issues and solutions:

Common mobile problems:

• Images too small to read

• Too many columns causing cramped layout

• Touch scrolling performance issues

• Memory constraints on older devices

Mobile optimization:

css

@media screen and (max-width: 767px) {
    .masonry-gallery {
        column-count: 1 !important; /* Single column on small screens */
        column-gap: 15px !important;
    }
    
    .masonry-gallery .gallery-item {
        margin-bottom: 15px !important;
        width: 100% !important;
    }
    
    .masonry-gallery img {
        width: 100% !important;
        height: auto !important;
        max-width: none !important;
    }
}

/* Improve touch scrolling performance */
.masonry-gallery {
    -webkit-overflow-scrolling: touch;
    transform: translateZ(0); /* Hardware acceleration */
}

Performance & Loading

Q: The masonry layout loads slowly or causes performance issues. How do I optimize? A: Performance optimization strategies:

1. Image optimization:

css

.masonry-gallery img {
    loading: lazy; /* Native lazy loading */
    decoding: async; /* Async image decoding */
}

2. Progressive loading:

javascript

pluginMasonryGallery({
    'progressiveLoad': true,
    'loadBatch': 10, // Load 10 images at a time
    'loadDelay': 100 // 100ms delay between batches
});

3. Hardware acceleration:

css

.masonry-gallery {
    transform: translateZ(0);
    will-change: auto;
    contain: layout;
}

.masonry-gallery .gallery-item {
    transform: translateZ(0);
    backface-visibility: hidden;
}

4. Reduce DOM manipulation:

javascript

pluginMasonryGallery({
    'useCSS': true, // CSS-only masonry when possible
    'debounceResize': 250, // Limit resize event frequency
    'lazyLayout': true // Don't calculate layout until needed
});

Q: The layout jumps around while images are loading. How do I fix this? A: Prevent layout shift during loading:

Method 1: Placeholder heights

css

.masonry-gallery .gallery-item {
    min-height: 200px; /* Minimum placeholder height */
    background-color: #f5f5f5; /* Placeholder background */
    transition: min-height 0.3s ease;
}

.masonry-gallery .gallery-item img {
    opacity: 0;
    transition: opacity 0.3s ease;
}

.masonry-gallery .gallery-item.loaded {
    min-height: auto;
}

.masonry-gallery .gallery-item.loaded img {
    opacity: 1;
}

Method 2: Aspect ratio preservation

css

.masonry-gallery .gallery-item {
    aspect-ratio: auto; /* Maintain aspect ratios */
}

.masonry-gallery .gallery-item::before {
    content: '';
    display: block;
    padding-bottom: 60%; /* Adjust based on average image ratio */
}

.masonry-gallery .gallery-item img {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    object-fit: cover;
}

Method 3: Wait for all images to load

javascript

pluginMasonryGallery({
    'waitForImages': true,
    'showPlaceholder': true,
    'placeholderColor': '#f5f5f5'
});

Advanced Customization

Q: Can I add hover effects or overlays to masonry gallery items? A: Yes, add interactive elements:

Basic hover overlay:

css

.masonry-gallery .gallery-item {
    position: relative;
    overflow: hidden;
}

.masonry-gallery .gallery-item::before {
    content: '';
    position: absolute;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background: rgba(0,0,0,0.7);
    opacity: 0;
    transition: opacity 0.3s ease;
    z-index: 2;
}

.masonry-gallery .gallery-item:hover::before {
    opacity: 1;
}

/* Text overlay */
.gallery-item-overlay {
    position: absolute;
    bottom: 20px;
    left: 20px;
    right: 20px;
    color: white;
    opacity: 0;
    transform: translateY(20px);
    transition: all 0.3s ease;
    z-index: 3;
}

.masonry-gallery .gallery-item:hover .gallery-item-overlay {
    opacity: 1;
    transform: translateY(0);
}

Lightbox integration:

html

<div class="masonry-gallery">
    <div class="gallery-item">
        <a href="#lightbox_/image1" class="gallery-link">
            <img src="/s/image1-thumb.jpg" alt="Image 1">
            <div class="gallery-item-overlay">
                <h3>Image Title</h3>
                <p>Image description</p>
            </div>
        </a>
    </div>
</div>

Q: How do I add captions or metadata to masonry gallery items? A: Caption implementation:

Method 1: Below image captions

css

.masonry-gallery .gallery-item {
    background: white;
    border-radius: 8px;
    overflow: hidden;
    box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}

.gallery-item-caption {
    padding: 15px;
    border-top: 1px solid #eee;
}

.gallery-item-caption h3 {
    margin: 0 0 5px 0;
    font-size: 16px;
    font-weight: 600;
}

.gallery-item-caption p {
    margin: 0;
    font-size: 14px;
    color: #666;
    line-height: 1.4;
}

Method 2: Overlay captions

css

.gallery-item-caption {
    position: absolute;
    bottom: 0;
    left: 0;
    right: 0;
    background: linear-gradient(transparent, rgba(0,0,0,0.8));
    color: white;
    padding: 20px 15px 15px;
    transform: translateY(100%);
    transition: transform 0.3s ease;
}

.masonry-gallery .gallery-item:hover .gallery-item-caption {
    transform: translateY(0);
}