Deep linking gives every item inside a Gallery a URL that reopens the Gallery on that exact item. When a visitor shares a photo, the link they paste does not just land on the page — it lands on the photo, with the Lightbox already open and the rest of the Gallery ready to browse. The same URLs are what social networks and search engines use to preview and index individual items.
Location FotoGrids → Settings → Sharing → Deep linking
What Deep Linking Solves #
Without deep linking, every share from a Gallery points at the same page URL. A visitor who clicks the share button on the 47th photo sends a friend a link that opens the top of the page — and that friend has to scroll, open the Lightbox, and click through 46 thumbnails before reaching the photo the share was actually about. Most of them do not bother.
Deep linking fixes the gap. FotoGrids gives each item its own addressable URL and writes the current item’s URL into the browser’s address bar as visitors navigate the Lightbox. When that URL is shared or pasted back into the browser, FotoGrids reopens the Gallery on the matching item — Lightbox first if one is available, or scrolled-and-highlighted inside the grid if the Gallery is configured without a Lightbox.
How the URLs Are Built #
FotoGrids uses two URL forms depending on where the Gallery is being viewed.
Standalone View Page
When a Gallery or Album is opened at its own URL (the standalone view page rendered by FotoGrids), each item is addressed by a query parameter:
https://example.com/gallery/winter-trip/?fg-item=482
The view page reads fg-item server-side and emits per-item Open Graph tags, so when the URL is shared the social network’s preview card shows the specific photo rather than the Gallery’s cover.
Embedded Gallery
When a Gallery is embedded inside a regular WordPress page (via a shortcode or block), the host page already has its own URL and its own Open Graph tags, so FotoGrids uses a URL fragment instead:
https://example.com/about/team/#fg-15-482
The fragment encodes both the Gallery ID and the item ID — #fg-{galleryId}-{itemId} — so the same page can hold multiple Galleries without their deep links clashing. Because fragments are client-side only, the host page renders normally and FotoGrids opens the Lightbox on the matching item once the page is interactive.
URL Sync While the Lightbox Is Open
As a visitor navigates between items inside the Lightbox, FotoGrids updates the URL in real time using history.replaceState. The current item’s deep link is always live in the address bar, so visitors who copy the URL from the location bar — not just from a share button — still get the deep link to the exact item they were looking at. Closing the Lightbox removes the deep link from the URL again.
URL sync uses history.replaceState rather than pushState, so the browser’s back button takes visitors back to where they came from instead of stepping them through every item they viewed inside the Lightbox.
Settings #
Enable Deep Linking
| Setting | Enable deep linking |
| Options | On Off |
| Default | On |
Turns deep linking on or off site-wide. When on, FotoGrids reads ?fg-item= and #fg- URLs on page load and opens the Lightbox on the matching item, and keeps the URL in sync as visitors navigate. When off, the URL is never modified and incoming deep links are ignored — share buttons still work but they only link to the page, not to the item.
Leave this on for almost every site. The only reason to turn it off is if a separate page-level mechanism — for example a single-page application shell — is already managing URL state and you do not want FotoGrids writing into the same address bar.
Embedded Galleries Share
| Setting | Embedded galleries share |
| Options | The specific image The page |
| Default | The specific image |
| Visible when | Enable deep linking is on |
What an item share links to when the Gallery is embedded inside a regular page rather than displayed on its own view page. Standalone view pages always share the per-item URL — this setting only changes the behaviour of embedded Galleries.
- The specific image — share buttons inside the Lightbox produce the
#fg-URL that reopens the host page on that exact image. Best when the Gallery is the main reason visitors come to the page, and you want item-level shares to land deep.- - The page — share buttons drop the item fragment and just share the host page URL. Best when the Gallery is one of several blocks on the page and you want shares to highlight the page as a whole, not a single image.
The choice is purely about what URL the share button passes to the social network. Visitors who copy the URL out of the address bar always get the deep-link form when the Lightbox is open, regardless of this setting.
Behaviour Without a Lightbox #
Not every Gallery opens a Lightbox. A Gallery can be configured so each thumbnail navigates to an external link, to the original image file, or does nothing at all. Deep links still work in this mode — FotoGrids scrolls the matching item into view and pulses a coloured outline around it for about two seconds, so visitors who land via a deep link immediately see which item the URL pointed to. Once the highlight fades, the Gallery behaves normally.
Sharing and Deep Linking Together #
Deep linking is the mechanism that makes social sharing land on the right thing. The two features are configured separately — sharing under Sharing → Enable sharing and deep linking under Sharing → Deep linking → Enable deep linking — but they almost always travel together. The Social Sharing article covers the share buttons, networks, placements, and tracking that depend on these URLs.
If you turn sharing on but deep linking off, share buttons inside the Lightbox still produce URLs — they just produce the page URL rather than the per-item URL, so every share from a Gallery lands at the same place.
Privacy and Caching Notes #
Deep links are plain query parameters and URL fragments. FotoGrids does not encode any visitor identity into them, does not generate signed tokens, and does not record which deep links are followed beyond the standard share-click and view-count statistics. URLs are safe to cache and safe to share publicly.
Page-level caching plugins generally do not need any configuration changes for deep linking. The ?fg-item= query parameter is read by the standalone view page’s PHP layer to emit per-item Open Graph tags, so caches that vary by query string will produce a separate cache entry per item — the expected behaviour. Fragment-based deep links (#fg-) are client-side only and never reach the cache layer.
