Back to Page
The Back to Page block renders a button that can behave in two different ways:
- History back when the visitor came from a matching page path.
- Normal navigation to a configured fallback URL when they did not.
It is designed for flows where a visitor lands on a detail page from a search or listing page and expects a button such as Back to Search Results or Back to Directory Search to preserve the previous page state.
Common examples include:
- site search results
- directory search results
- resource library results
- filtered archive or listing pages
What this block creates
When you insert Back to Page, it creates a nested core block structure:
core/buttonscore/button(inside the Buttons block)
This means you are styling a real Gutenberg Button, not a custom button UI.
All the normal Button settings are available because the visible button is a native core/button.
Field
This block adds one custom setting in the block sidebar.
Return Page URLs
Enter one possible return page URL per line.
- Example:
/directory-search/ - Example:
/search/ - Example:
https://example.com/member-directory/
How it works:
- The first valid URL is used as the button's normal fallback destination.
- All valid configured paths are used when checking whether the button should use browser history back behavior.
- Query strings and hash fragments are ignored for matching.
- Query strings and hash fragments are preserved on the fallback URL.
This is useful when the same detail page can be reached from more than one listing or search experience.
For example, you might configure:
/directory-search//search/
If the visitor came from either of those paths, the button can use browser history to preserve the exact previous state.
How navigation behavior works
On the frontend, the nested button always renders as a normal link to the first configured fallback URL.
JavaScript then checks the browser referrer and history state when the button is clicked.
When the block uses history back
The block calls browser back behavior when all of the following are true:
- the visitor has a usable browser history entry
document.referreris available- the referrer path matches one of the configured return page paths
Path matching is tolerant of:
- query strings
- hash fragments
- trailing slash differences
This allows flows like:
- visitor searches or filters a directory
- visitor clicks a result
- visitor lands on the detail page
- visitor clicks Back to Search Results
- browser returns to the previous page with the original state intact
When the block uses normal navigation
If the referrer does not match any configured path, or there is no usable browser history, the button behaves like a normal link and loads the first configured fallback URL.
This is the expected behavior for cases like:
- direct entry to the detail page
- opening the detail page in a new tab
- arriving from a non-matching page
- missing or stripped referrer headers
Fallback priority
When multiple URLs are configured:
- The first valid URL is used as the rendered
href. - Every valid configured path is eligible for history-back matching.
That means a setup like this:
/directory-search/
/search/
behaves as follows:
- If the visitor came from
/directory-search/, the block uses history back. - If the visitor came from
/search/, the block also uses history back. - If the visitor came from anywhere else, the button loads
/directory-search/because it is the first configured fallback URL.
Styling and configuration
Because the block contains a native Button, you can configure it normally using the standard Gutenberg UI:
- Button style
- Colors
- Typography
- Border
- Spacing
- Width
- Alignment and layout through the outer Buttons block
The default button text is Back to Search Results, but you can change the label using the normal Gutenberg Button editing controls.
Example use cases
Directory single pages
Configure:
/directory-search/
/search/
Use this when a profile or record page can be reached from both a dedicated directory search and the site-wide search.
Resource detail pages
Configure:
/resources/
/search/
Use this when a resource detail page may be reached from a filtered archive or a site-wide search page.
Single known source page
Configure just one URL:
/events/
Use this when all visitors are expected to come from the same listing page.
Troubleshooting
The button went to the fallback page instead of going back
Usually this means one of these conditions was true:
- the referrer path did not match any configured path
- the page was opened directly or in a new tab
- the browser did not provide a referrer
- the browser did not have a usable history entry
In those cases, the block intentionally falls back to normal link navigation.
The query string was not used for matching
This is expected.
The block compares only the page path when deciding whether to use history back. Query strings and hash fragments are ignored for matching so that filtered result pages still count as the same source page.
The fallback URL was not the one I expected
The block always uses the first valid configured URL as the normal fallback destination.
If order matters, place the preferred fallback page first in the list.
Can I style this like a normal Gutenberg button?
Yes.
The visible button is a native core/button, so standard theme and editor button controls still apply.
Technical notes (for developers)
- Block name:
yoko-core/back-to-page - Rendered server-side via
render.php. - Frontend behavior is handled in
view.js. - The nested button link is rewritten with:
data-back-to-page="1"data-back-to-page-fallback-url="..."data-back-to-page-fallback-path="..."data-back-to-page-match-paths="[...]"
- The first valid configured URL becomes the rendered fallback
href. - All valid configured paths are normalized and compared against
document.referreron click. - Matching ignores query strings, hash fragments, and trailing slash differences.