Docs / Cards & Grids / Masonry Gallery

Masonry Gallery

An organic, flowing image grid that arranges photos of any aspect ratio into a tight Pinterest-style mosaic. Supports a click-to-zoom lightbox, optional category filtering, and three visual styles for everything from clean portfolios to seamless full-bleed mosaics.

View live preview → Jump to settings ↓

→ Start Here

The most-used controls live here so editors can shape the gallery without scrolling. Heading toggle + alignment, column counts per breakpoint, image gap, visual style, lightbox, and the optional category filter.

Show Section Heading

Type: boolean (toggle) Default: true

Show or hide the section heading area (badge h6, title h2, description p) above the gallery grid. Turn it off when the gallery follows a stronger heading in the row above and the images should read as a continuation.

Heading Alignment (Desktop)

Type: choice Default: center Shown when: Show Section Heading is on

Text alignment for the heading area on desktop (993px and above).

  • left - Left
  • center - Center (default)
  • right - Right

Heading Alignment (Tablet/Mobile)

Type: choice Default: center Shown when: Show Section Heading is on

Text alignment for the heading area on tablet and mobile devices (below 992px). Set independently from desktop so editors can center on phones while keeping desktop left-aligned.

  • left - Left
  • center - Center (default)
  • right - Right

Columns (Desktop)

Type: choice (select) Default: 3

Number of columns on desktop. Tablet always uses 2 columns; mobile uses the value from Columns (Mobile) below.

  • 2 - 2 Columns
  • 3 - 3 Columns (default)
  • 4 - 4 Columns
  • 5 - 5 Columns

Columns (Mobile)

Type: choice (select) Default: 2

Number of columns on mobile (below 575px). Tablet always uses 2 columns. Use 1 for tall, full-width portrait shots; 2 for the standard mosaic; 3 for thumbnail-style grids.

  • 1 - 1 Column
  • 2 - 2 Columns (default)
  • 3 - 3 Columns

Column Gap

Type: number (slider, 0-40, step 2) Default: 12px

Space between images in pixels. Set to 0 with Gallery Style 3 (Seamless) for a flush, edge-to-edge mosaic. 8-16px works for most standard galleries.

Enable Lightbox

Type: boolean (toggle) Default: true

When on, clicking any image opens it full-size in a lightbox overlay with prev/next navigation. Turn off when the gallery is decorative only or images link elsewhere.

Enable Category Filter

Type: boolean (toggle) Default: false

Adds a dropdown above the grid that lets visitors filter the gallery by category tags. Tag each image via the Filter Tags field in the Content group. Turn this on if you have a portfolio with multiple categories (e.g. landscape, portrait, product).

Filter Label

Type: text Default: Filter: Shown when: Enable Category Filter is on

The label text rendered next to the filter dropdown. Localize this for non-English sites (e.g. "Filtrar:", "Filtrer :").

Animate Filter Transitions

Type: boolean (toggle) Default: true Shown when: Enable Category Filter is on

Adds a smooth fade animation when switching between filter categories. Turn off for an instant filter swap (useful when image counts are large and re-layout feels janky).

"Show All" Label

Type: text Default: Show All Shown when: Enable Category Filter is on

The label for the filter option that clears the current filter and shows every image. Localize for non-English sites.

/// Content

The section heading rich text, the scroll-in animation, and the repeating gallery images themselves (each with its own caption and filter tags).

Section Heading

Type: richtext Default: blox Theme / Masonry Gallery Module / one-line description Shown when: Show Section Heading is on

The badge + title + description block above the gallery grid. The default markup is <h6> (rendered as a pill badge if Badge Style is enabled), <h2> for the title, and <p> for the description. Keep the h6 short (2-4 words) so the badge pill stays compact.

Fade-In Animation

Type: choice (select) Default: none

Entrance animation triggered when the section scrolls into view. Adds a 30px slide from the chosen direction plus opacity.

  • none - None (default)
  • fade-up - Fade Up
  • fade-down - Fade Down
  • fade-left - Fade from Left
  • fade-right - Fade from Right
  • fade - Fade Only (no slide)

Reduced motion: When a visitor has prefers-reduced-motion: reduce, the animation is skipped and the gallery renders fully visible.

Gallery Images

Type: group (repeater) Min: 1 / Max: 50 / Default count: 6

The repeating list of images that make up the gallery. Add, remove, and drag-to-reorder items in the editor. Each item exposes the three sub-fields below.

Image

Type: image Default: empty src, alt "Gallery image", loading lazy

The image file for this gallery tile. Masonry preserves each image's native aspect ratio so portraits, landscapes, and squares can coexist. Always set meaningful alt text via the HubSpot file picker for accessibility.

Tip: Use unique filenames when uploading or replacing images. HubSpot's CDN caches by URL, so overwriting a file with the same name can leave visitors seeing the stale image for hours.

Caption (optional)

Type: text Default: empty

Optional caption rendered beneath the image. Leave blank to hide the caption row for that tile. Styled via the Caption Text Color and Caption Font Size fields under Gallery Style.

Filter Tags

Type: text Default: empty Shown when: Enable Category Filter is on

Comma-separated category tags used by the filter dropdown (e.g. landscape, portrait). Keep spelling and case consistent across images or each variant will appear as a separate filter option. An image can belong to multiple categories.

Custom ID & Classes (code)

Developer hooks for adding custom CSS or JS targeting. Leave blank for most pages.

CSS ID

Type: text Default: empty

Sets an id="..." on the section element. Must be unique on the page. Useful for anchor links (e.g. #gallery) and JS targeting. Only use one.

CSS Class

Type: text Default: empty

Additional classes (space-separated) appended to the section element's class list. Useful when applying page-specific overrides via the page's custom CSS.

Style Settings

Everything visual: gallery tile styling, filter chrome, badge tier, section dividers, and the wrapping row's background, width, and spacing.

Tile-level visual controls: rounded corners, hover shadow, and caption typography.

Image Border Radius

Type: number (slider, 0-30, step 1) Default: 12px Shown when: Gallery Style is Style 1 or Style 2

Rounded corners on each gallery image. 12px matches the theme's default tile rounding; 0 for hard corners, 24+ for very soft edges. Hidden for Style 3 (Seamless) because that style uses flush, unrounded tiles.

Hover Shadow Color

Type: color Default: #000000 @ 25% opacity

The drop-shadow color and opacity applied to an image when a visitor hovers over it. Stay under 35% opacity for tasteful shadow; above that hover feels heavy.

Caption Text Color

Type: color Default: #666666 @ 100% opacity

Text color for image captions. Defaults to a soft grey that reads as secondary metadata beneath the image. Match this to your section background for legibility on colored backgrounds.

Caption Font Size

Type: number (slider, 10-18, step 1) Default: 13px

Font size for image captions in pixels. Keep small (12-14px) so captions stay clearly subordinate to the imagery.

/// Filter Style

Visual settings for the category filter UI. Only shown when Enable Category Filter is on.

Filter Alignment

Type: choice (select) Default: center Shown when: Enable Category Filter is on

Horizontal alignment of the filter dropdown above the gallery grid.

  • left - Left
  • center - Center (default)
  • right - Right

Filter Text Color

Type: color Default: #1a1a1a @ 100% opacity Shown when: Enable Category Filter is on

Text color for the filter label and inactive filter options.

Active Filter Color

Type: color Default: #1a1a1a @ 100% opacity Shown when: Enable Category Filter is on

Text color for the currently-selected filter option (visual indication of which category is active).

Active Filter Background

Type: color Default: #f5f5f5 @ 100% opacity Shown when: Enable Category Filter is on

Background color behind the active filter option (pairs with Active Filter Color above to form the selected pill).

/// Badge Style

Optional pill-badge styling for the <h6> in the Section Heading rich text.

Show Badge Styling

Type: boolean (toggle) Default: true

Styles the <h6> inside the Section Heading as a pill badge instead of a plain heading. Turn off to render the h6 as a regular small heading.

Badge Style

Type: choice (select) Default: badge-primary Shown when: Show Badge Styling is on

Picks which badge tier to apply. Colors, borders, and typography for each tier are configured globally in Theme Settings > Badge.

  • badge-primary - Primary (default)
  • badge-secondary - Secondary
  • badge-three - Three
  • badge-four - Four
  • badge-five - Five
  • badge-six - Six

/// Section Dividers

Decorative SVG shapes that sit at the top or bottom of the section, useful for blending into the section above or below.

Top Divider

Type: choice (select) Default: none

Decorative shape at the top of the section. All 9 shape options are rendered as inline SVG matching the divider color you set.

  • none - None (default)
  • wave-1 - Wave 1 (Gentle)
  • wave-2 - Wave 2 (Sharp)
  • wave-3 - Wave 3 (Multi)
  • wave-4 - Wave 4 (Smooth)
  • wave-5 - Wave 5 (Layered)
  • tilt - Tilt (Angled)
  • curve - Curve (Arc)
  • triangle - Triangle

Top Divider Color

Type: color Default: #ffffff @ 100% opacity Shown when: Top Divider is set to any shape (not None)

Color of the top divider shape. Set this to match the background color of the section above so the divider reads as a transition between the two sections.

Top Divider Height

Type: number (slider, 20-200, step 10) Default: 60px Shown when: Top Divider is set to a wave, curve, or triangle shape

Height of the top divider shape in pixels. Larger values make the shape more dramatic; smaller values keep it subtle.

Angle Height (Top)

Type: number (slider, 0-300, step 10) Default: 100px Shown when: Top Divider is set to tilt

Height of the angled top divider. Only applies to the tilt shape (other shapes use Top Divider Height instead).

Flip Top Divider

Type: boolean (toggle) Default: false Shown when: Top Divider is set to any shape (not None)

Mirror the top divider shape horizontally. Useful for alternating wave direction between adjacent sections.

Bottom Divider

Type: choice (select) Default: none

Decorative shape at the bottom of the section. Same 9 options as the top divider.

  • none - None (default)
  • wave-1 - Wave 1 (Gentle)
  • wave-2 - Wave 2 (Sharp)
  • wave-3 - Wave 3 (Multi)
  • wave-4 - Wave 4 (Smooth)
  • wave-5 - Wave 5 (Layered)
  • tilt - Tilt (Angled)
  • curve - Curve (Arc)
  • triangle - Triangle

Bottom Divider Color

Type: color Default: #ffffff @ 100% opacity Shown when: Bottom Divider is set to any shape (not None)

Color of the bottom divider shape. Set this to match the background color of the section below.

Bottom Divider Height

Type: number (slider, 20-200, step 10) Default: 60px Shown when: Bottom Divider is set to a wave, curve, or triangle shape

Height of the bottom divider shape in pixels.

Angle Height (Bottom)

Type: number (slider, 0-300, step 10) Default: 100px Shown when: Bottom Divider is set to tilt

Height of the angled bottom divider. Only applies to the tilt shape.

Flip Bottom Divider

Type: boolean (toggle) Default: false Shown when: Bottom Divider is set to any shape (not None)

Mirror the bottom divider shape horizontally.

Divider Under Content

Type: boolean (toggle) Default: false Shown when: Bottom Divider is set to any shape (not None)

Puts the bottom divider behind content so any overlapping buttons or links remain clickable. Turn on if the bottom divider visually overlaps any interactive element.

/// Row Settings

The section's wrapping row controls: background (color, gradient, image), content width, and per-breakpoint padding.

Background (Image, Video, Color, Etc.)

Type: group Default Type: none

The Background Type dropdown drives which sub-controls appear:

  • none - No background (default; section inherits the page bg)
  • color - Solid Color, reveals Background Color picker
  • gradient - Gradient, reveals Gradient Top Color, Gradient Bottom Color, and 8 Gradient Direction options (Top to Bottom, Bottom to Top, Left to Right, Right to Left, and the four diagonals)
  • image - Image, reveals Background Image, Background Size (cover/contain/original), Background Position (center/top/bottom/left/right), Enable Overlay toggle, Overlay Color, Enable Blur toggle, Blur Amount (0-20px)

Note: The group is labeled "Image, Video, Color, Etc." in the editor but the current build does not include a video background option. Background Type only exposes none/color/gradient/image.

Size (Content Width)

Type: group Default: standard

Sets the max-width of the gallery's content container. Standard and Slim widths are set in Theme Settings > Layout.

  • standard - Standard (default)
  • slim - Slim (narrower variant)
  • custom - Custom, reveals a Custom Width number input (600-1920px, default 1200)

Spacing (Around Content)

Type: group (per breakpoint)

Padding controls for the row, set independently for desktop, tablet, and mobile. Each breakpoint exposes a top/bottom/left/right spacing input. Defaults:

  • desktop - 100px top, 100px bottom, 0 left, 0 right
  • tablet - 60px top, 60px bottom, 0 left, 0 right
  • mobile - 40px top, 40px bottom, 15px left, 15px right