# Blocks & options

> Reference for the Wisp Gallery blocks – Filterable Gallery, Gallery Filter, Gallery Media Query and Gallery Posts – with every option, value and default.

Source: https://wispgallery.com/docs/blocks/

Wisp Gallery adds three blocks and one Query Loop variation. The photos inside a gallery stay ordinary core blocks, so everything core offers for Image, Query Loop and Featured Image keeps working.

> Options marked **(Pro)** are set with Wisp Gallery Pro. The free plugin renders all of them, so a gallery keeps its look when a license ends. The [Pro features](#pro) are listed at the end.

| Block | What it does |
| --- | --- |
| **Filterable Gallery** 
`wisp-gallery/gallery` | The container. Lays out its content in one of five layouts, with sizes per device, captions, hover effects, a lightbox and filter animations. |
| **Gallery Filter** 
`wisp-gallery/filter` | Buttons or a dropdown that filter one gallery, or every gallery on the page. Place it anywhere – above, below or beside the gallery. |
| **Gallery Media Query** 
`wisp-gallery/media-query` | Media Library images by Gallery Category, inside a gallery. New uploads show up without editing the page. |
| **Gallery Posts** 
`core/query` variation | Posts as gallery items, built from the regular Query Loop, Post Template and Featured Image blocks. |

## Images, posts and media in one gallery

A gallery can hold Image blocks, a Gallery Posts query and a Gallery Media Query side by side. On the front end the groups dissolve into one shared grid (`display: contents`), so one filter and one lightbox cover all of them. Each post item links to its page; post titles and excerpts use the same caption styles as image captions.

## Filterable Gallery

Sizes marked “per device” have a desktop, tablet (under 782px) and mobile (under 600px) value; the device switcher in the panel is tied to the editor’s preview size. Defaults come first.

| Panel | Option | Values |
| --- | --- | --- |
| Layout | Layout | masonry, rows, grid, carousel, accordion (picker with diagrams) |
|  | Columns | per device: 3 · 2 · 1 |
|  | Row height | per device: 240 · 200 · 160 px – the row, tile, slide, card or strip height, depending on the layout |
|  | Row size (grid) | aspect ratio, fixed height |
|  | Aspect ratio (grid) | 1; tablet and mobile “same as larger screens” or their own |
| Items | Click behavior | link, lightbox, media file, none |
|  | Open in new tab | off (link and media file) |
|  | Hover effect | zoom, none; lift, color on hover, dim others (Pro) |
|  | Reveal on scroll | off; rise, fade; zoom, blur, tilt up, wipe, pop, flip, slide, iris (Pro). Masonry, rows, grid, carousel |
|  | Stagger (Pro) | 2.5 rem (0–6): the scroll distance between neighbours starting; 0 brings a row in together (masonry, rows, grid, with reveal on) |
| Lightbox | Style (Pro) | dark, light, frosted (blurred page behind) |
|  | Opening animation | zoom from thumbnail, fade, none |
|  | Captions, image counter | on, on |
|  | Colors (Pro) | background, text and icons, buttons |
|  | Arrow icon (Pro) | chevron, thin chevron, bold chevron, arrow, triangle (the carousel sets it under Navigation) |
|  | Download, share (Pro) | off, off: download the original upload; the system share sheet or the link to the clipboard |
|  | Camera settings (Pro) | off: camera, lens, aperture, shutter and ISO from the EXIF data, under the caption |
|  | Deep links (Pro) | off: the address names the open photo (`#gz-123`), so a link opens it; Back closes the lightbox |
| Captions | Presets (Pro) | No captions, Theme caption, Card, Gradient overlay, Hover reveal, Solid bar, Frosted glass, Clean text |
|  | Position | hidden, below, on the image, on hover |
|  | Look (Pro) | plain (gradient on images), solid, frosted glass, minimal |
|  | Alignment, size (Pro) | start, center, end; XS, S, M, L |
|  | Colors (Pro) | text, background |
| Filtering | Filter animation | move + fade, none; crossfade, slide, zoom (Pro) |
|  | Gallery ID | for filter blocks to target |
|  | Filter by (Pro) | Gallery Categories or any public taxonomy |
| Load more (Pro) | Show items | all at once; in steps, with a button; in steps, on scroll |
|  | Items per step | 12 (1–60) |
| Block supports |  | wide and full alignment, anchor, text and background color, gap (row and column), corner radius |

### Click behavior

**Link** (the default) follows each image’s own link – nothing more. Set links per image with **Link** in the image’s block toolbar. When no image in the gallery has a link, the sidebar shows a warning, because clicks would do nothing; pick *Lightbox* or *Media file* instead if the photos should open larger.

The carousel and accordion have options of their own – arrows, autoplay, looping, centering and more. They are listed on the [Layouts](https://wispgallery.com/docs/layouts/) page.

### Captions

Captions are hidden until you choose otherwise; their position is free, their look is a Pro setting. A caption preset sets position, look, alignment and size in one click; each preset in the picker shows a small preview of its look. Presets only set regular attributes, so every value stays editable afterwards. Captions apply to image captions and to post titles and excerpts alike. A frosted-glass caption sits inset on the photo, and its corners follow the image’s corner radius (minus the inset), so the two curves stay parallel.

### Lightbox

Set *Click behavior* to **Lightbox** and photos open in a native `<dialog>`: it zooms out of the thumbnail, pages through the photos that are currently visible (so it respects the filter) with the arrow buttons, arrow keys or a swipe, and shows the caption and a counter. Click the photo, press `Esc` or use the close button to close it. While it is open, the page behind doesn’t scroll.

## Gallery Filter

| Panel | Option | Values |
| --- | --- | --- |
| Presets (Pro) |  | Compact chips, Tabs, Segmented control, Soft tags, Minimal links, Theme buttons, Theme links, Pills + dropdown on mobile, Dropdown – each with a small preview in the picker |
| Styles |  | Theme button; Theme link, Soft, Pills, Segmented, Underline (Pro) |
| Appearance | Display as | buttons, dropdown on mobile, dropdown |
|  | Button size (Pro) | small, XS, M, L, theme |
|  | Dropdown label | text |
| Settings | Gallery | one gallery by ID, or all on the page |
|  | Categories | which terms to show, and in which order |
|  | Taxonomy (Pro) | Gallery Categories or any public taxonomy; must match the gallery’s |
|  | “All” button, label | on, “All” |
|  | Counts | off, on (inline); badge, superscript, number and badge colors (Pro) |
|  | Hide empty, multi-select | on, off |
|  | URL parameter (Pro) | e.g. `category` → `?category=food`, also rendered on the server |
| Block supports |  | alignment, layout (justification, orientation, wrap), gap, text, background and button colors, typography, border, shadow |

The **Theme button** style (the default) uses your theme’s button element styles; **Theme link** (Pro) uses its link color, hover and underline. Typography, border, shadow, gap and the “Button” color from the block’s own settings apply to the buttons, in the free plugin too.

## Gallery Media Query

Put it inside a Filterable Gallery to show Media Library images by category. Settings: categories, or *Use the archive’s category* (on a Gallery Category archive: that category and its children); number of images (24); order by date, title or random, ascending or descending; image size; link to none, the file or the attachment page; captions.

## Gallery Posts

Insert a Query Loop and choose the **Gallery Posts** variation, or add posts or pages from the empty gallery. Each post becomes an item: its Featured Image, with the Post Title – and a Post Excerpt, if you add that block to the template – as the caption. Filter posts the same way as images – by Gallery Categories, which posts and pages share with media, or by any other taxonomy such as regular post categories.

## Wisp Gallery Pro

Pro adds editor controls to the same blocks. Everything they set is rendered by the free plugin, so galleries never change or break when a license ends; only changing those settings needs Pro again.

- **Videos:** Media Library files, YouTube (also Shorts), Vimeo, TikTok and Instagram next to photos. Add them from *Add content → Videos* or paste a link into the gallery; the provider’s thumbnail is saved as the poster. Hover plays a muted preview (*Play videos on hover*), a click plays it in the lightbox.
- **Load more:** show a large gallery in steps, with a button or on scroll.
- **Albums:** a Filterable Gallery inside a gallery becomes one cover tile, with its name and photo count, that opens its photos in the lightbox.
- **WooCommerce products:** WooCommerce’s Product Collection block inside a gallery, and a shop pattern. Product items show their price and an add to cart link in the lightbox (a Query Loop of products does that in the free plugin too).
- **Lightbox extras:** themes and colors, download and share buttons, camera settings and deep links.
- **Design controls:** caption looks and presets, filter styles and presets, button sizes, count styles and colors, carousel arrow design and arrows that follow the mouse, autoplay timing, more hover, reveal and filter effects, and filtering by any taxonomy.
- **Pattern pack:** ready-made galleries for artists, weddings, menus, property listings and more, under *Patterns → Wisp Gallery Pro*.