Tutorial: Filterable Gallery
Sixty images, five categories, a filter bar, a search field and pagination — with counts that always match.
What you'll build: one big gallery that behaves like five small ones, with a search field for the images nobody can quite remember the name of.
Time: about 20 minutes, most of it assigning categories.
You'll use: Masonry · Categories · Filter & Search · Ajax Pagination
Before you start
- 40–80 images uploaded.
- Titles and captions filled in. Search matches against title, caption and description — images with none of those can never be found. This is the step people skip and then wonder why search is broken.
- A rough idea of your categories. Five or six is the sweet spot; more than eight and the bar becomes its own navigation problem.
Step 1: Build the gallery
- Create a page, add the Shaped Gallery block.
- Layout → Masonry. It keeps every image's proportions, which suits a mixed set, and it repacks cleanly when a filter hides tiles.
- Add from Media, select everything, Add to Gallery.
- Layout Settings → Columns: 4 desktop, 3 tablet, 2 mobile.
- Horizontal and Vertical Gap: 16 px, 12 px on mobile.
Step 2: Create the categories
- Click Edit Gallery on the block toolbar.
- In the left sidebar, Add Category. Create five, named the way a visitor would say them — Weddings, Portraits, Landscape, Street, Studio.
Name them for visitors
These labels appear on the front end. Behind the scenes beats bts-2024 every time.
Step 3: Assign images
The fast way is in batches:
- Tick every wedding photo.
- Bulk actions → Add to category → Weddings.
- Repeat per category.
For a handful of stragglers, click a category to enter assignment mode — the modal says "Selecting images for Weddings — tap images to add or remove" — and tap them.
Check your work
Click Unassigned in the sidebar. When it says All images are assigned to a category, you're done.
An image can be in several categories
A studio portrait can be both Portraits and Studio. It'll show under either chip.
Close the modal.
Step 4: Turn on the filter bar
Open Image Filter & Search:
| Control | Set to | Why |
|---|---|---|
| Image Filter | On | |
| Filter Style | Button | Reads as clickable more clearly than Minimal. |
| Display Count | On | Sets expectations before the click. |
| Show 'All' | On | Gives visitors a way back. |
| Label for 'All' | Everything | Friendlier than "All". |
| Gap Between Filters | 12 px |
The bar appears above the gallery in the editor preview.
Empty categories never show
A category with nothing in it is dropped from the bar, so you can create categories freely and only the populated ones reach visitors.
Step 5: Add search
Still in the same panel:
| Control | Set to | Why |
|---|---|---|
| Image Search | On | |
| Search Bar Style | Boxed | Reads as a field; searches as you type. |
| Placeholder | On, text Search photos | |
| Width | 30 % desktop, 100 % mobile | Use the device switcher. |
Now that both are on, three more controls appear:
| Control | Set to |
|---|---|
| Filter & Search Orientation | Inline |
| Filter & Search Gap | 16 px |
| Justify Filter & Search | Space Between |
Chips on the left, search on the right.
Check this at phone width
Inline chips plus a search field is a lot for a 375 px screen. If it's cramped, switch Orientation to Stacked and Filter Style to Dropdown — the combination that survives a phone.
Step 6: Style the bar
Open the Style tab in the same panel:
- Typography — a size that sits below your body text, around 14 px.
- State switcher → Normal: Text Color a muted grey, Background Type a very light fill.
- State switcher → Hover & Active: Text Color white, Background Type your brand colour.
- Border Radius 999 px for pill chips, or 4 px for square ones.
The active chip uses the Hover styling
There are two states, not three. Make sure the active chip is obviously different from the inactive ones — contrast, not a slight tint. Accessibility →
Step 7: Add pagination
With 60 images, shipping all of them is wasteful.
- Layout Settings → Ajax Pagination on.
- Open the new Ajax Pagination panel.
- Pagination Type → Load More.
- Show Per View → 12.
- Button Label →
Show more photos. - Alignment → Center.
Why the counts still work
This is the part worth understanding. Filtering happens on the server, against the whole gallery — not by hiding tiles on the current page.
So clicking Weddings (14) gives you all fourteen wedding photos, paged twelve at a time. Not "the wedding photos that happened to be in the first twelve". The number on the chip is the number you get.
Step 8: Publish and test
Publish, then in a private window:
- [ ] Click each chip — the grid repacks with no holes left behind
- [ ] The counts match what you see
- [ ] Type a word from a caption — matching images appear as you type
- [ ] Type two words — only images matching both appear
- [ ] Filter, then Show more photos — you stay inside the filter
- [ ] Try it all at phone width
- [ ] Tab to a chip and press Enter — it works from the keyboard
What you built
One gallery that behaves like five, with search, paging that respects the filter, and counts that tell the truth.