A WordPress plugin for building advanced image and video galleries using a custom post type. Supports masonry and square grids, Swiper slider, GLightbox lightbox, dynamic category filtering, AJAX load more, lazy loading, drag-and-drop reordering, and video support. No page builder required.
Everything the plugin does at a glance.
Masonry or square 1:1 grid with hover overlays, category badges, video badges, and optional titles.
Standalone touchscreen-ready slider with autoplay, loop, captions, and per-instance configuration.
Click any item to open a full-screen lightbox with prev/next navigation, keyboard support, and video playback.
Filter buttons auto-generated from item categories. Hidden when no categories are set.
Paginate large galleries without a page reload. Lazy loading re-initialises automatically for new items.
Add an MP4 URL to any item. Shows thumbnail + play icon in the grid; plays in GLightbox on click.
mgs_gallery — create as many galleries as you need, no ACF requiredpost_id — display different galleries on different pages[mgs_gallery] for the grid and [mgs_gallery_slider] for a standalone slider| Requirement | Minimum | Notes |
|---|---|---|
| WordPress | 6.0+ | Uses register_post_meta, wp_json_encode |
| PHP | 7.4+ | Uses null coalescing ??, arrow functions |
| ACF / Plugins | None | The plugin registers its own CPT and meta — no third-party plugins needed |
| jQuery | Any | Bundled with WordPress core — used for admin drag-and-drop and AJAX |
Go to Plugins → Add New → Upload Plugin, choose the zipped plugin folder, then click Install Now. Or FTP the folder directly to wp-content/plugins/mosaico-gallery-slider/.
Click Activate Plugin. A new Galleries menu item (photo icon) will appear in the WordPress admin sidebar.
Go to Galleries → Add New. Give it a title, then scroll to the Gallery Items meta box. Click Add Item to add images, titles, categories, and optional video URLs.
Go to Galleries list view. In the Shortcode column next to your gallery, select the shortcode type from the dropdown and click Copy.
Edit any page or post, paste the shortcode into the content, and publish. Your gallery will appear on the front end.
The fastest path from zero to a working gallery.
[mgs_gallery][mgs_gallery post_id="42" grid="square"][mgs_gallery_slider post_id="42"]post= is the ID. Or use the Shortcode column — it prefills the correct post_id for you.[mgs_gallery]The primary gallery shortcode. Renders a responsive image/video grid with configurable columns, optional fixed height and width per item, category filter bar, AJAX load-more button, and an optional inline Swiper thumbnail strip at the bottom.
| Attribute | Type | Default | Options | Description |
|---|---|---|---|---|
post_id |
integer | 0 | any post ID | ID of a single Gallery post to display. When 0, items from all published gallery posts are merged into one gallery. |
grid |
string | masonry | masonry · square |
masonry uses CSS columns — images keep their natural height. square uses CSS grid with aspect-ratio:1/1 — images are cropped to fill the tile. |
per_page |
integer | 8 | any positive integer | Number of items shown on initial load. A Load More button appears automatically when the total exceeds this number. |
swiper |
string | no | yes · no |
Append an auto-scrolling Swiper thumbnail strip below the grid. For a fully standalone slider use [mgs_gallery_slider] instead. |
show_title |
string | yes | yes · no |
Show or hide the item title below each image (masonry) or as a caption overlay (square). Has no effect when an item's title field is empty. |
columns |
integer | 4 | 1 – 6 | Number of columns in the grid. Automatically reduced on smaller screens — capped at 2 on tablet, 1 on mobile. Works for both masonry and square grid modes. |
height |
integer (px) | 0 | any positive integer | Fixed height in pixels for every gallery item. Images and videos are cropped with object-fit:cover to fill the height. When 0, images retain their natural height. |
width |
integer (px) | 0 | any positive integer | Fixed width in pixels for every gallery item. Useful in masonry mode to create uniform card widths. When 0, items fill the column width naturally. |
// All galleries, masonry, 8 per page, titles visible
[mgs_gallery]
// Single gallery, square grid, 12 items per page
[mgs_gallery post_id="55" grid="square" per_page="12"]
// 3 column masonry, natural height
[mgs_gallery post_id="55" columns="3"]
// 2 column square grid
[mgs_gallery post_id="55" grid="square" columns="2"]
// Fixed height 300px, 4 columns
[mgs_gallery post_id="55" height="300" columns="4"]
// Fixed height + width per item, 3 columns
[mgs_gallery post_id="55" height="250" width="300" columns="3"]
// Single column, full width, fixed height — timeline style
[mgs_gallery post_id="55" columns="1" height="400"]
// Masonry without titles
[mgs_gallery post_id="55" show_title="no"]
// Masonry grid + inline Swiper strip at the bottom
[mgs_gallery post_id="55" swiper="yes"][mgs_gallery] shortcodes on the same page, only the first one will have a working Load More button because the button ID dg-load-more is unique per page. For multiple paginated galleries, use separate pages.[mgs_gallery_slider]A fully standalone Swiper slider. No grid, no filter bar, no load-more button. Drop it anywhere — a page, post, or alongside a [mgs_gallery] shortcode. Multiple instances on the same page each get a unique ID so they never interfere with each other.
| Attribute | Type | Default | Options / Range | Description |
|---|---|---|---|---|
post_id |
integer | 0 | any post ID | ID of the gallery post to pull slides from. When 0, items from all published gallery posts are merged. |
per_view |
integer | 4 | 1 – any | Max slides visible at once on desktop (≥992 px). Automatically capped on smaller screens: 3 on ≥768 px, 2 on ≥576 px, 1 on mobile. |
height |
integer (px) | 200 | min 80 | Slide image height in pixels. Images are cropped with object-fit:cover so all slides share the same height regardless of original dimensions. |
autoplay |
string | yes | yes · no |
Auto-advance slides at the interval set by delay. Pauses when the user interacts with the slider. |
delay |
integer (ms) | 3500 | min 500 | Milliseconds between autoplay advances. Only used when autoplay="yes". |
loop |
string | yes | yes · no |
Loop back to the first slide after the last one. |
speed |
integer (ms) | 500 | min 100 | Slide transition animation duration in milliseconds. |
show_title |
string | yes | yes · no |
Show the item title as a gradient caption overlay at the bottom of each slide. Hidden when the title field is empty. |
// Simplest usage — slider for one gallery, all defaults
[mgs_gallery_slider post_id="42"]
// Taller slides, slower autoplay
[mgs_gallery_slider post_id="42" height="360" delay="5000"]
// 3 slides wide, no autoplay, no loop, no titles
[mgs_gallery_slider post_id="42" per_view="3" autoplay="no" loop="no" show_title="no"]
// Single full-width slide, hero style
[mgs_gallery_slider post_id="99" height="480" per_view="1" delay="6000"]
// Fast transition, no autoplay, 2 slides wide
[mgs_gallery_slider post_id="42" per_view="2" autoplay="no" speed="250"][mgs_gallery_slider] shortcodes on the same page are fully independent — each gets a unique auto-incremented ID (dg-slider-1, dg-slider-2, …) so they never conflict.The plugin registers a custom post type mgs_gallery labelled Galleries in the admin. It appears in the sidebar with a photo icon.
true — galleries are individually accessible on the front end if neededshow_in_rest: true — compatible with the block editorpost capabilities — any user who can edit posts can manage galleriesThe Gallery Items meta box appears on every Gallery edit screen. Each row is one gallery item.
| Field | Type | Required | Description |
|---|---|---|---|
Image |
WP Media | required | Click the upload area or drag an image. The plugin stores the attachment ID and URLs for full, large, and medium sizes. The large size is shown in the grid; medium is used in the Swiper strip. |
Title / Caption |
text | optional | Shown below the image in masonry mode, as an overlay in square mode, and as a caption in the slider. Also used as the lightbox heading and image alt text fallback. |
Category |
text | optional | Free-text category tag. Items sharing the same category get a shared filter button. Leave blank to exclude the item from filtering. Matching is case-insensitive. |
Video URL |
URL | optional | Direct URL to an MP4 file. When set, the grid item shows the image thumbnail with a play icon overlay and VIDEO badge. Clicking opens the video in GLightbox. If no image is set, a native <video> element is rendered inline instead. |
Grab the ⠿ handle on the left side of any item row and drag it to a new position. The order is saved when you publish or update the post.
Click + Add Item in the footer bar to append a new row with a slide-in animation. Click the ✕ button on any row to remove it. Both actions update the item count in the header instantly.
The Galleries list view has a Shortcode column next to every gallery title. It provides a dropdown of ready-made shortcode variants for that gallery's post_id:
| Dropdown option | Shortcode generated |
|---|---|
| Default Gallery | [mgs_gallery post_id="…"] |
| Square Grid | [mgs_gallery post_id="…" grid="square"] |
| Without Titles | [mgs_gallery post_id="…" show_title="no"] |
| With Swiper Strip | [mgs_gallery post_id="…" swiper="yes"] |
| 3 Columns | [mgs_gallery post_id="…" columns="3"] |
| 2 Columns | [mgs_gallery post_id="…" columns="2"] |
| Fixed Height | [mgs_gallery post_id="…" height="300"] |
| Slider | [mgs_gallery_slider post_id="…"] |
| Slider No Titles | [mgs_gallery_slider post_id="…" show_title="no"] |
| 3-col Slider | [mgs_gallery_slider post_id="…" per_view="3"] |
| Slider No Autoplay | [mgs_gallery_slider post_id="…" autoplay="no"] |
Select a variant, then click Copy — the shortcode is copied to your clipboard.
Uses CSS columns to create a Pinterest-style layout. Images retain their natural aspect ratio. The column count responds to screen size:
| Viewport | Columns |
|---|---|
| ≥ 992 px (desktop) | 4 |
| 577–992 px (tablet) | 2 |
| ≤ 576 px (mobile) | 1 |
Uses CSS display:grid with aspect-ratio:1/1 per cell. Every image is cropped with object-fit:cover to fill the square. The item title, when visible, appears as a semi-transparent bar along the bottom of each tile. Column breakpoints are the same as masonry.
[mgs_gallery grid="masonry"] // natural heights, Pinterest-style
[mgs_gallery grid="square"] // uniform 1:1 tilesThe default column count is 4 on desktop. Use the columns attribute to override this for both masonry and square modes. The value is automatically capped at 2 on tablet and 1 on mobile regardless of what you set.
[mgs_gallery columns="3"] // 3 columns desktop, 2 tablet, 1 mobile
[mgs_gallery columns="2"] // 2 columns desktop, 2 tablet, 1 mobile
[mgs_gallery columns="1"] // single column — full width itemsThe filter bar appears automatically above the grid whenever at least one gallery item has a non-empty Category field. It is hidden entirely when no categories are set.
Nature and nature are the same categoryClicking any grid item opens GLightbox — a full-screen overlay with the full-size image or video. Features include:
source: 'local' for direct MP4 filesWhen the total gallery items exceed the per_page value, a Load More button appears below the grid. On click it:
admin-ajax.php// Show 4 items initially, load 4 more on each click
[mgs_gallery post_id="42" per_page="4"]Grid images use a two-layer lazy loading strategy:
data-srcIntersectionObserver (with a 100px root margin) swaps in the real URL as the image enters the viewportopacity 0 → 1 fade plays once the image has fully loadedIntersectionObserver support fall back to immediate loadingThe standalone slider uses the native loading="lazy" attribute directly on slide images.
Any gallery item can have a video by entering a direct MP4 URL in the Video URL field of the meta box.
<video> element inline with playback controls.<video> element in the slide.source: 'local' for direct MP4 files. YouTube and Vimeo embeds are not supported — host the file on your own server or a CDN and use the direct file URL.[mgs_gallery
post_id="23"
grid="square"
per_page="12"
][mgs_gallery
post_id="23"
grid="masonry"
columns="3"
height="280"
per_page="9"
][mgs_gallery_slider
post_id="5"
height="480"
per_view="1"
delay="6000"
show_title="yes"
]// Grid at the top
[mgs_gallery post_id="55" grid="masonry"]
// Slider strip further down the same page
[mgs_gallery_slider post_id="55" height="160" per_view="4"][mgs_gallery_slider post_id="23" height="220" autoplay="yes"]
[mgs_gallery_slider post_id="47" height="220" autoplay="no" loop="no"][mgs_gallery
post_id="99"
grid="square"
per_page="8"
show_title="yes"
swiper="yes"
]assets/css/admin.css and assets/css/gallery.cssassets/js/admin.js and assets/js/gallery.jsincludes/ files: CPT, MetaBox, Helpers, Shortcodes, Ajax, Assets, AdminColumns[mgs_gallery]: show thumbnail + play icon overlay; video plays in GLightbox on click[mgs_gallery_slider]: same thumbnail + play icon behaviour, consistent with gallery gridsource: 'local' applied for direct MP4 filesshow_title attribute to both shortcodescolumns attribute to [mgs_gallery] — override desktop column count (1–6)height attribute to [mgs_gallery] — fixed pixel height per item with object-fit:coverwidth attribute to [mgs_gallery] — fixed pixel width per itemmgs_gallery with built-in meta box — no ACF required[mgs_gallery] shortcode with masonry / square grid, filter bar, load more, lazy load, and lightbox[mgs_gallery_slider] standalone Swiper slider shortcodeI'd love to hear about your project. Drop me a message or reach out directly at hello@webdevparvez.com