Skip to main content
View Categories

Toolkit: Photo Gallery

Photo Gallery turns a property’s photos into an Airbnb-style browsing experience, a hero grid, a full-screen photo browser that can be organized room by room, and a swipeable mobile carousel, so guests can explore a listing the way they already expect to.


What it does #

Guests judge a rental heavily on its photos, and a plain photo strip or single slideshow undersells a property that actually looks great in person. Photo Gallery presents your property’s photos the way major booking sites do: one large photo up front, a handful more sitting alongside it, and a “Show all photos” button that opens everything in a full-screen browser.

Here is what a guest experiences on a property page:

  • The property’s first photo appears large and prominent, with up to four more shown beside it.
  • A Show all photos button opens every photo in a full-screen browser, laid out in an easy-to-scan mix of full-width and paired rows.
  • Clicking any photo, in the grid or the full-screen browser, opens it at full size in a dark, Airbnb-style single-photo view, with a Close button and a “2 / 14” counter in the header. Guests can step through the rest with the arrow buttons, the left and right arrow keys, or by dragging the photo left or right with a mouse or a finger; the photo follows the drag and settles on the next or previous shot.
  • In the single-photo view, dragging a photo downward closes it; the photo shrinks and the dark backdrop fades as they follow the drag. Letting go partway through springs the photo back to center instead of closing. Swiping to another photo and dragging down to close both work when the photo is at its normal size.
  • In the single-photo view, guests can zoom in to check a detail, such as a countertop or the view from a balcony. On a phone or tablet, they pinch with two fingers: the photo scales and moves with their fingers, and it stays zoomed when they let go. On a laptop, a trackpad pinch or Ctrl plus the scroll wheel zooms in on the pointer, a magnifier button in the header zooms in and back out, and the + and – keys do the same. Zoom goes up to four times normal size. While zoomed in, one finger or the mouse moves the photo around, and it stops at the photo’s edges. Moving to another photo starts it back at normal size. The first zoom past normal size loads a larger version of the photo where one exists, so the detail holds up.
  • The Escape key steps back one level at a time: from a single photo back to the full-screen browser, at the spot the guest left, and from the browser back to the page.
  • Opening and closing the full-screen browser plays a short, smooth fade, and stepping between photos in the single-photo view fades the incoming photo in, whether by button, arrow key, or drag. Guests who have reduced motion turned on in their device skip the animation entirely.
  • On phones, the hero area itself becomes a swipeable carousel, with a small counter (for example, “2 / 14”) that always shows the guest where they are in the set.

Photo Gallery does not resize, crop, or reorder anything on its own. It shows your property’s photos in the order they are already saved, and whichever photo is first becomes the large hero image. If a property has fewer than five photos, the grid simply shows however many are available, with the “Show all photos” button on the last one. If a property has no photos saved at all, the gallery area shows a plain note, “No photos found for this property,” instead of leaving a broken or empty gap.

Every photo loads at a size matched to the visitor’s screen, and the hero photo is prioritized so it appears quickly, so pages load fast without sacrificing image quality.

Photo Gallery displays still photos only. Video is not currently supported.

The 3D tour button #

If your listings carry a virtual tour, a 3D Tour button sits beside Show all photos on the gallery, so guests can walk through the home without leaving the property page. On phones, the button sits to the left of the compact “Show all” pill.

  • The tour opens in a centered window over the page, in a full-screen window, or in a new browser tab, whichever you choose.
  • The tour loads only when a guest asks for it, and it stops when they close the window.
  • A listing with no tour in its field shows no button, and its gallery looks exactly as before.

The button reads the tour from a custom field on each listing. The field can hold a Matterport model id (an 11-character code such as SxQL3iGyoDo), a tour link from Matterport or another provider, the m= part of a Matterport share link, or pasted embed code. Links that start with http:// are upgraded to https://. A value that is none of these shows no button.

The photo tour: photos grouped by room #

With Group photos by room switched on, the full-screen browser becomes a photo tour, the way Airbnb organizes a listing:

  • A Photo tour index sits at the top: one tile per room, showing the room’s first photo and its name. Tapping a tile scrolls straight to that room. Photos that belong to no room close the tour under a “More photos” tile.
  • Once a guest scrolls past the index, a row of room names stays pinned under the header, with the room on screen marked. Tapping a name jumps to that room, so nobody has to scroll back to the top to switch rooms. The row scrolls sideways when the names do not fit and keeps the marked name in view. Back at the top, the full index with its cover photos returns.
  • Below the index, each room gets its own section. On a desktop, the room name holds on the left while that room’s photos scroll on the right, laid out as a mosaic of one, two or three photos per block. On phones, the index becomes a swipe strip and the sections run in one column.
  • Under a bedroom’s name, the beds in that room print on their own (“Queen bed”, “Single bed · 2 bunk beds”), read from the bed data your listing already carries. A bed line only appears when the room’s name matches one of the listing’s spaces by name and no other room on the listing shares that name.
  • Below the beds, an optional details line shows whatever you have written in a custom field for that room: amenities, a view, a note. Long text shows two lines with a “Show more” link.

The hero grid at the top of the page and the mobile carousel keep the normal gallery order; only the full-screen browser changes.

Rooms come from the PMS (Guesty room assignments) or from photo captions when HomeRunner can read a room name from them. A listing with neither keeps the normal “Show all photos” grid, so turning the option on is safe for a mixed portfolio.

Room links: open the tour at one room #

A guest who asks about the kitchen or the primary bedroom usually gets a link to the property page and has to find those photos from there. A room link takes them straight to the room. Add #room= and the room’s name to the end of a property page address, and the photo tour opens on that room’s section.

For a property at https://yoursite.com/property/the-lantana/, the link to its primary suite is https://yoursite.com/property/the-lantana/#room=primary-suite.

  • Opened from an email, a text message or another website, the property page loads with the photo tour already open on that room.
  • Clicked on the property page itself, for example in the description, the tour opens and glides to the room without reloading the page.
  • When the guest closes the tour, the #room= part leaves the address bar, so a refresh shows the normal property page.
  • A name that matches no room on the listing does nothing, and the property page loads as usual.

Room links need Group photos by room switched on, and they work on any page where the gallery shows that property’s photos. There is nothing else to turn on.

How to turn it on #

1. Switch on the module #

In the HomeRunner Toolkit Hub, switch on Photo Gallery.

2. Place the gallery #

In your page builder, add the shortcode [hrtk_photo_gallery] to the property page template, or to any specific page where you want the gallery to appear. Or, if your property page already uses the default photo slider, turn on Replace the photo slider section below and skip the shortcode entirely.

That is the whole setup. There is no separate photo upload step; the gallery reads directly from the photos already saved on each property listing.

If your site was already using the older Property Gallery shortcode from a WPCode snippet, [property_photo_gallery], you do not need to change anything. That tag still works exactly the same way, so existing templates keep rendering as-is.

By default, the gallery shows the photos of whichever property page it is placed on. To point it at a specific listing instead, for example featuring one property’s photos on a different page, add that property’s ID: [hrtk_photo_gallery id="123"].

3. Shape the hero grid #

The Layout section of the panel shows a live preview of the hero grid, at reduced scale, using photos from your most recent property. It repaints as you change the settings; nothing changes on the site until you save.

By default, the hero grid stretches to the full width of its container. To cap and center it instead, turn off Full width gallery and set a Maximum width. You can also override the width for one placement of the shortcode without touching the Hub setting, for example [hrtk_photo_gallery max_width="900"], or [hrtk_photo_gallery max_width="0"] to force that one placement full width regardless of the Hub setting.

Large photo width sets how much of the grid the large photo takes; the four smaller photos share the rest. Space between photos and Corner radius finish the look, and Round decides whether the rounding applies to the gallery’s four outer corners or to every photo.

4. Group photos by room (optional) #

Under By room, switch on Group photos by room. The Rooms list below it fills with the rooms found on your ten newest listings, in the order guests would see them.

  • Drag a room, or use its arrows, to change the order. Rooms on listings not in the list follow in gallery order, and photos with no room close the tour under “More photos”. Back to gallery order clears a custom order.
  • Type over a room’s name to change the heading guests see. Two rooms given the same heading show as one section, which is how you merge “Patio” and “Pool Deck” into one “Outdoor Living” section, or split them back apart.
  • The Guests see strip under the list shows the headings in their final order as you edit.
  • Copy id gives you a room’s identifier for a rule that should apply to that one room only.

For rules about rooms that are not on your newest listings, open Edit as text. Room order takes one heading or room type per line (a type such as BEDROOM or FULL_BATHROOM pulls every room of that kind). Room overrides takes one rule per line: the room name or room id, an equals sign, and the heading to show. A name covers every room with that name; an id covers one room.

Pin the room index, on by default, keeps the row of room names under the header while guests scroll the tour. Switch it off to keep the room index at the top of the tour only.

5. Add a details line under a room (optional) #

Room details is on by default and shows nothing until a listing carries a matching custom field. Create a custom field on the listing named after the room, following the Room details field pattern. With the default pattern, {room}details, the room “Bedroom 2” reads a field named bedroom2details, the same field Bedroom Showcase uses, and “Living Room” reads livingroomdetails. The room name is lowercased and reduced to letters and digits, so “Pool & Patio” reads poolpatiodetails.

Write the details as one line (“Queen bed · Sofa bed · Air conditioning”), one item per line, or a bulleted list; each becomes part of the line. A room is also tried under the name your PMS gave it, so renaming a room in the Rooms list keeps its field.

6. Link to a room (optional) #

  • Open the photo tour on the property and note the room’s heading, for example “Primary Suite”.
  • Write the name in lowercase with hyphens between the words, and add it to the property page address after #room=, as in #room=primary-suite.
  • Use the link anywhere you would use the property link: a reply to a guest, a newsletter, or a sentence in the property description.

Capital letters, spaces and punctuation do not matter, so “Pool & Patio” is #room=pool-patio. A room that has not been merged with another also answers to the name your PMS gave it, so a link written before you renamed the heading keeps working. If two rooms on a listing share a heading, a link by that heading opens nothing, because it could mean either room; give the rooms different headings in the Rooms list, or link by the PMS name of the one you mean. The closing “More photos” section has no link.

7. Add a 3D tour button (optional) #

Under 3D tour, type the name of the custom field that holds each listing’s tour in 3D tour field, for example matterport. Use the field name as it appears in your PMS or in the External Custom Fields store, or a post meta key. Leave it empty to keep the button off.

Then choose Open the tour in: a modal, a full-screen modal, or a new tab. Pick a new tab for tour providers that do not allow their tours to be shown inside another page. Change Button text if you want something other than “3D Tour”.

8. Style the gallery buttons (optional) #

Under Button style, pick colors for the Show all photos and 3D Tour buttons, on desktop and on phones. The live preview shows the result before you save. Leave a color empty to keep the white button with dark text, or, when a site brand palette is set in Toolkit Settings, the brand ink with white text. The button corner radius follows the brand radius while it is left at 8 (see Brand Palette).

  • With only a Background, the text and icon switch to white or dark, whichever reads better on it, and the outline matches the background. The hover shade is a little darker.
  • Text and icon and Outline override those automatic choices. The outline shows on desktop only.
  • Button corner radius rounds the desktop buttons from 0 (square) to 30 pixels. Phone buttons stay pill-shaped.

Settings #

SettingWhat it controls
Replace the photo slider sectionOn single property pages, automatically swaps the default photo slider for Photo Gallery, no template editing or shortcode placement needed. If your page template already places [hrtk_photo_gallery] directly, or a property has no photos, the page is left untouched. Off by default.
Full width galleryThe hero grid stretches to the full width of its container. Turn off to cap the gallery at a maximum width and center it. On by default.
Maximum widthPixel cap applied when Full width gallery is off, between 320 and 3000. Default: 1200px. The [hrtk_photo_gallery] shortcode can override it per placement with max_width="…" (use 0 for full width).
Large photo widthHow much of the hero grid the large photo takes, between 25% and 75%; the four smaller photos share the rest. 37.5% is the original layout, 50% matches Airbnb. Default: 37.5%.
Space between photosGap between the hero photos, in pixels, from 0 to 60. The mobile carousel and the full-screen browser are not affected. Default: 3px.
Corner radiusRounding in pixels, from 0 to 100. Default: 0, square corners.
RoundWhere the radius applies: only the outer corners of the gallery as one block, or every photo, so the gaps between photos get rounded edges too. Default: outer corners.
Group photos by roomIn the “Show all photos” view, photos are listed one section per room with the room name as its heading, behind a photo tour index. The hero grid keeps the gallery order. Off by default.
RoomsThe rooms on your ten newest listings, to reorder by dragging and rename by typing. Rooms that share a heading show as one section.
Room order (Edit as text)One heading or room type (BEDROOM, FULL_BATHROOM) per line, in the order they should lead. Rooms not listed follow in gallery order. Empty by default.
Room overrides (Edit as text)One rule per line, the room name or room id, an equals sign, the heading to show. A name covers every room with that name, an id one room. Empty by default.
Room detailsA line under the room name in the “Show all photos” view, read from a custom field on each listing. Bedroom beds print on their own; this adds what you write. Long text shows two lines with “Show more”. On by default.
Pin the room indexIn the “Show all photos” view, a row of room names stays under the header while the guest scrolls, with the room in view marked. Tapping a name jumps to that room. Off keeps the room index at the top of the tour only. Available when Group photos by room is on. On by default.
3D tour fieldThe custom field on each listing that holds its tour. Accepts a Matterport model id, a tour link, or embed code. Letters, digits, spaces, dots, dashes and underscores, up to 100 characters. Empty means no 3D Tour button. Empty by default.
Open the tour inHow the tour opens: a modal, a full-screen modal, or a new tab. Default: a modal.
Button textThe label on the tour button, up to 40 characters. Empty uses “3D Tour”.
Button backgroundBackground color of the Show all photos and 3D Tour buttons, as a hex color. Empty is white.
Button text and iconText and icon color of those buttons. Empty picks white or dark text to suit the background.
Button outlineOutline color of those buttons on desktop. Empty matches the background, or stays dark on the white button.
Button corner radiusCorner rounding of the desktop buttons, in pixels, from 0 to 30. Phone buttons stay pill-shaped. Default: 8.
Room details fieldThe custom field name, with {room} standing for the room name in lowercase letters and digits. Default: {room}details.

Tips #

  • Photo Gallery is commonly placed as one section of a property page alongside other single-property elements. See Single Property Homepage for how those pages are typically laid out, and Property Section Nav if your property pages use section navigation.
  • If the gallery shows “No photos found for this property,” the listing itself does not have photos saved yet. Add photos to the property record, not just the page, and the gallery picks them up automatically.
  • If Group photos by room is on but a listing still shows the plain grid, its photos carry no room yet. In Guesty, assign the photos to rooms on the listing and let the listing sync; the Rooms list in the Hub says “No room data yet” until some listing has them.
  • If a room link opens the property page but not the photo tour, compare the name in the link with the room’s heading in the tour, and check that Group photos by room is on. A listing without rooms keeps the plain grid, and a room link does nothing there.
  • Only one Photo Gallery can appear on a page at a time. If the shortcode has been added more than once (for example, in both a template and the page content), only the first one renders; remove the extra one. Replace the photo slider section stands down automatically if the shortcode is already present, so the two options do not conflict.
  • Zoom shows the detail your photos actually contain, and HomeRunner never enlarges a photo past its original size. If close-up detail matters (linens, a view, a kitchen), keep the largest original on the listing.
  • If you use Bedroom Showcase, you can set its Photo tap to Photo Gallery so a tap on a bedroom photo opens this full-screen browser scrolled to that photo. Both need to be on the same page for the same property.
  • Captions saved on individual photos double as the descriptive text screen readers announce for that photo, so it is worth keeping them accurate and specific.
  • If you already fill in bedroom details for Bedroom Showcase, those same fields feed the photo tour’s details lines with no extra work.