How to Set Up Search & Results Page Redirects

In most shops, search spans two pages. Your results page holds the components that do the work: vviinn-text-search, the filters, and vviinn-results. The search bar also appears elsewhere — on the homepage, or in a header on every page.

results-page-url links the two. Set it on the search components, and a search typed on the homepage opens your results page with the query in the URL. The results page reads that query and runs the search. Image uploads work the same way.

Without it, you write the glue yourself: listen for the search event, build the URL, navigate, parse it on arrival, then update it each time the shopper searches again.

Because the search lives in the URL, results can also be linked to, reloaded, and indexed. Results in a modal can’t.

flowchart LR
    A["Entry point<br/>homepage or header<br/>vviinn-text-search"] -->|"navigates to<br/>/search?query=shoes"| B["Results page<br/>vviinn-text-search, filters<br/>vviinn-results"]
    B -->|reads query / searchId from URL| C[Search & Discovery Engine]
    C -->|ranked products| B

Data flow for a text query. An image upload takes the same path, carrying searchId instead of query.

Set up

results-page-url goes on every vviinn search component on both pages, always with the same value:

<!-- Homepage -->
<vviinn-text-search results-page-url="/search"></vviinn-text-search>

<!-- Results page (/search) -->
<vviinn-text-search results-page-url="/search"></vviinn-text-search>
<vviinn-results     results-page-url="/search"></vviinn-results>

Each component reads the prop differently. Away from the results page it is the destination to navigate to. On the results page it means already here, so a later search updates the page instead of redirecting again — and it is what tells vviinn-results to look for a search in the URL at all.

The value can be a relative path or an absolute URL. The only other attribute these components require is token — locale and mode have defaults, and the filter markup that usually surrounds them is left out here. For a complete, runnable results page, see the Search Page example.

Use cases

Text search

A search at the entry point navigates to the results page, with the query in the URL:

/search?query=shoes

The vviinn-text-search input on the results page is pre-filled from that URL parameter.

Visual search

The same search bar redirects on image upload too, and needs no second redirect prop for it — the bar builds its image-search button already configured that way. What it does need is mode="extended", which is what puts image search in the bar at all; mode defaults to basic, text only. The search is passed by ID rather than by text:

/search?searchId=abc-123

For a standalone visual-search entry point — vviinn-vps-button or vviinn-vps-widget — add show-results-in-modal="false" alongside results-page-url. Without it the modal renders the results itself and never redirects.

<vviinn-vps-button
  results-page-url="/search"
  show-results-in-modal="false"
></vviinn-vps-button>

To keep showing the uploaded image on the results page, add a vviinn-cropper there — its default save-image-mode="once" reuses the image the shopper just uploaded. The button’s own props are listed in its Storybook playground.

Matching your URL structure

If query and searchId don’t fit the URLs you already use, rename them with results-page-params. It takes a URLSearchParams-style string, so results-page-params="query=q&searchId=sid" turns the URLs above into:

/search?q=shoes&sid=abc-123

Set the same value everywhere you set results-page-url — the components that write the URL and the vviinn-results that reads it — or they won’t agree on what to look for.

SPA routing

In a single-page app a full page load discards client state. Listen for the vviinnRedirect event, call preventDefault(), and navigate with your own router instead.

vviinnRedirect is not specific to this feature, though. Three redirects share the event, told apart by detail.source: text-search and visual-search are the results-page redirect, while auto-suggest is a Query-to-URL Mapping. That last one points wherever the merchant configured, often outside your search flow, so routing it internally will usually break it. Branch on the source rather than intercepting everything:

document.addEventListener("vviinnRedirect", (event) => {
  const { source, url } = event.detail;
  if (source === "auto-suggest") return; // let the widget follow it

  event.preventDefault();
  router.push(url);
});

The event also carries query for a text search or searchId for an image search.

Doing it manually

For a URL shape the prop can’t produce, or a redirect decision that depends on your own state, omit results-page-url and drive it yourself: listen for vviinnTextSearchStarted (detail.query) and vviinnImageUploadFinished (detail.searchId), then hand them back on the results page through search-query on vviinn-text-search and search-id on vviinn-results.

You then own what the prop was handling — keeping the URL current as the shopper searches again, and preserving the uploaded image across reloads. The Search Page has full code for both approaches side by side.

Good to know

How a component decides it has arrived

The check is on path alone: the path of the current URL against the path in results-page-url, trailing slashes normalized, query string ignored. So /search, /search/, and https://shop.com/search all match the same page.

If your results page actually lives at a different path than the prop gives, no component ever counts as arrived and every search redirects.

Query-to-URL Mapping takes priority

Your Text Search campaign can send specific queries to a URL of their own — the Query-to-URL Mapping setting in Panel. A mapped query goes there and never reaches your results page, whatever results-page-url says. Visual search behaves the same way when the API suggests a URL for an uploaded image.

The precedence is intentional, and it explains why one particular search can appear to ignore the redirect.

`vviinnTextSearchStarted` stops firing

While results-page-url is set and the shopper is away from the results page, vviinnTextSearchStarted is not emitted — vviinnRedirect replaces it, as described under SPA routing. Move any analytics or other logic hanging off it accordingly.

Common questions

What is an automatic search redirect? It navigates from the search bar to a dedicated results page instead of rendering results in a modal, and passes the search in the URL.

How do I enable it? Set results-page-url on vviinn-text-search (on both the starting page and the results page) and on vviinn-results on the results page.

Does it work for image search too? Yes. The same search bar redirects on image upload. A standalone vviinn-vps-button or vviinn-vps-widget also needs show-results-in-modal="false".

Where is the uploaded image kept during the redirect? In the browser’s localStorage, under vviinnCropperImageSrc (with vviinnDetectedObjects beside it). The URL carries only searchId, and the results themselves come from that — the stored image is what lets vviinn-cropper show the picture again on the results page. With the default save-image-mode="once" it is read once and cleared immediately; "always" keeps it across reloads, "never" stores nothing.

Do I need to write code to load the results? No. vviinn-results parses query and searchId from the URL and runs the search automatically once results-page-url is set.

Can I rename the URL parameters? Yes, with results-page-params — for example query=q&searchId=sid. Use the same value on every component.

Will a search on the results page redirect again? No. results-page-url on the results-page components tells them they’re already there, so later searches update the results in place.

Why does one particular query ignore the redirect? It most likely has a Query-to-URL Mapping in your Text Search campaign, which takes priority over the results-page redirect.

Text Search — the campaign settings behind the results, including the Query-to-URL Mapping described above
Visual Search — the campaign settings behind image search: barcode reading, OCR, and object detection