Hug Media Gallery Query Loop

Purpose

This plugin provides a custom block for the WordPress editor that allows you to display galleries of images automatically, based on their Media Gallery. Instead of manually picking images for every gallery, you simply tag your images and this block does the rest.

Note: This plugin does require the installation and activation of the “Media Library Categories” plugin.

Step 1. Prepare Your Images

Before using the block, your images must be categorized.

1. Go to Media > Library in your WordPress dashboard.
2. Ensure your images have a Media Gallery assigned (e.g. “Kitchens”, “Bathrooms”, or “Willowhaven”).

Step 2. Add the Hug Media Gallery Query Loop block

1. Open the page or post where you want the gallery.
2. Click the (+) inserter and search for “Hug Media Gallery Query Loop”.
3. When first added, the block will show a placeholder asking you to select a category.

Step 3. Block Settings (The Inspector)

Once the block is selected, look at the Settings Sidebar (right-hand side) under the “Media Gallery Filters” panel.

Filters & Selection

  • Media Category: Select the category of images you want to display. The gallery will update instantly.
  • Sort By: Choose the order of images:
    • Date: Show the newest work first
    • Title: Alphabetical order
    • Order: Manual menu order. In the Media Library, you should see a column called “Order”. This allows you to add a numerical value that is used in the Sorting options.
  • Order Direction:
    • Choose Descending (Newest/Z-A) or Ascending (Oldest/A-Z)

Layout & Appearance

There are four gallery layouts:

  • Grid
    • Standard uniform squares/rectangles; best for clean, organized look.
  • Masonry
    • Pinterest-style columns where images keep their natural height; best for mixed portrait and landscape images.
  • Tiled
    • Images span multiple columns or rows based on their shape.; creates a “collage” feel.
  • Fancy
    • A “recursive split” layout that fills a specific container area perfectly; high-end, artistic portfolio pages.
  • Number of Columns (Grid/Masonry only): Choose between 1 and 6 columns.
  • Image Resolution: Choose the quality (Thumbnail, Medium, Large, or Full). Note: “Large” is usually best for speed, while “Full” is best for photography-heavy pages.

Interaction

  • Enable Lightbox: If turned on, users can click an image to open it in a full-screen zoomable view (powered by PhotoSwipe).
  • Show Image Titles: Displays the image title text directly under the image in the gallery.

Important Tips for Success

The “Fancy” Layout Warning
When using the Fancy (Recursive Split) layout, the WordPress editor will show a placeholder message: “The complex recursive rendering is disabled in the editor”. Don’t panic: This is normal. To see the actual “Fancy” layout, you must Preview or View the live page.

Automatic Resizing
The “Fancy” layout is designed to be responsive. If a user rotates their phone or resizes their browser window, the gallery will automatically recalculate the math to make sure the images still fit the screen perfectly without gaps.

Troubleshooting
– Gallery is empty: Check that images are actually assigned to the category you selected in the Media Library

– Images look blurry: Increase the Image Resolution setting in the sidebar to “Large” or “Full”.