Search Page

Using the vviinn widgets as separate components gives you greater control over the layout and supports a wider range of use cases. For example, you can combine Text Search and Visual Search while refining results with filters, and display them on the same page or even on different pages.

Available components

vviinn-text-search — a text search input field that allows users to search by text or upload an image
vviinn-filters, vviinn-extended-filters — a set of filters that allow users to refine their search results
vviinn-results — a container that displays the search results

Examples

Using results on a different page

This is the most common use case: the search component is on one page (e.g., the homepage), and results are displayed on a separate search results page. The Search & Results Page Redirects guide covers this setup step by step.

Automatic redirect (recommended)

Set the results-page-url prop on the search component. The widget handles redirection and URL parameter passing automatically.

Code
Technical Details

<!-- Homepage -->
<vviinn-text-search
  token="YOUR_READ_ONLY_TOKEN"
  mode="extended"
  locale="en-US"
  results-page-url="/search"
></vviinn-text-search>

<!-- Results page (/search) -->
<vviinn-text-search
  token="YOUR_READ_ONLY_TOKEN"
  mode="extended"
  locale="en-US"
  results-page-url="/search"
></vviinn-text-search>

<vviinn-filters></vviinn-filters>
<vviinn-extended-filters locale="en-US"></vviinn-extended-filters>

<vviinn-results
  token="YOUR_READ_ONLY_TOKEN"
  locale="en-US"
  product-details-new-tab="true"
  results-page-url="/search"
></vviinn-results>

How it works:

When the user searches on the homepage, the widget redirects to the results page with URL parameters (e.g., /search?query=shoes or /search?searchId=abc-123). URL parameter names can be customized via results-page-params (e.g., results-page-params="query=q&searchId=sid" → /search?q=shoes&sid=abc-123). Set this prop on both the search component and vviinn-results so they agree on the parameter names.
On the results page, vviinn-results with results-page-url set automatically parses URL parameters and triggers the corresponding search.
The vviinn-text-search input is automatically populated with the query from the URL.
On the results page, results-page-url ensures that the widget does not redirect again — subsequent searches update results in place.
You can intercept the redirect by listening to the vviinnRedirect event and calling event.preventDefault() (e.g., for SPA routing).
Visual search (vviinn-vps-button, vviinn-vps-widget) supports the same flow: set results-page-url and show-results-in-modal="false" to redirect to the results page after image upload instead of rendering results inside the modal.

Manual redirect

For full control over the redirect logic, omit results-page-url and handle navigation yourself using events.

Code
Technical Details

<!-- Homepage -->
<script>
  document.addEventListener("vviinnTextSearchStarted", ({ detail }) => {
    // Redirect using detail.query (text search)
  });

  document.addEventListener("vviinnImageUploadFinished", ({ detail }) => {
    // Redirect using detail.searchId (image search)
  });
</script>
<vviinn-text-search
  token="YOUR_READ_ONLY_TOKEN"
  mode="extended"
  locale="en-US"
></vviinn-text-search>

<!-- Results page -->
<script>
  // Get query or searchId from URL
</script>
<vviinn-filters></vviinn-filters>
<vviinn-extended-filters locale="en-US"></vviinn-extended-filters>

<!-- Text Search example: -->
<vviinn-text-search
  token="YOUR_READ_ONLY_TOKEN"
  mode="extended"
  locale="en-US"
  search-query="RECEIVED_QUERY"
></vviinn-text-search>

<vviinn-results
  token="YOUR_READ_ONLY_TOKEN"
  locale="en-US"
  product-details-new-tab="true"
></vviinn-results>

<!-- Image Search example: -->
<vviinn-cropper token="YOUR_READ_ONLY_TOKEN" width="300"></vviinn-cropper>

<vviinn-text-search
  token="YOUR_READ_ONLY_TOKEN"
  mode="extended"
  locale="en-US"
></vviinn-text-search>

<vviinn-results
  token="YOUR_READ_ONLY_TOKEN"
  search-id="RECEIVED_SEARCH_ID"
  locale="en-US"
  product-details-new-tab="true"
></vviinn-results>

In this example, the vviinn-text-search component is on the first page, and the rest of the components are on the second page.

First, add event listeners to capture the query for a text search or the searchId for a Visual Search.
Pass this data to the second page via the URL and use it to get the results.
- For Text Search, use the search-query attribute to pass the query to the vviinn-text-search component.
- For Visual Search, use the search-id attribute to pass the searchId to the vviinn-results component. To show the image, use the vviinn-cropper component. The default save-image-mode="once" lets the Cropper reuse the uploaded image.

Implementation tips

Scenario	Recommendation	Component/Attribute
Automatic redirect to results page	Set the results page URL — the widget handles redirect and URL parameters automatically	`<vviinn-text-search results-page-url="/search">` or `results-page-url="https://shop.com/search"`
Intercepting the redirect (SPA)	Listen to the `vviinnRedirect` event and call `preventDefault()` to handle navigation yourself	`document.addEventListener("vviinnRedirect", ...)`
Performing new searches on results page	Don’t pass parameters again — components handle new queries automatically	No attributes needed
Supporting page reloads (manual redirect)	When handling the redirect manually, update the URL after each search using the browser History API so the page can be reloaded	Use `pushState()` or `replaceState()`
Preserving uploaded image on reload	Save the image between page reloads for Visual Search	`<vviinn-cropper save-image-mode="always">`

Single page example

<style>
  vviinn-text-search {
    margin: 10px 0;
  }

  .search-page-wrapper {
    display: flex;
    gap: 20px;
  }

  .search-page-wrapper-aside {
    flex: none;
    width: 250px;
  }

  @media screen and (max-width: 768px) {
    .search-page-wrapper-aside {
      display: none;
    }
  }

  .search-page-wrapper-result {
    flex: 1;
  }

  .search-page-wrapper-result-filters {
    display: flex;
    flex-direction: column;
    gap: 10px;
    margin: 10px 0 !important;
    overflow-x: auto;
  }

  .search-page-wrapper-result-filters vviinn-extended-filters {
    display: none;
  }

  @media screen and (max-width: 768px) {
    .search-page-wrapper-result-filters vviinn-extended-filters {
      display: block;
    }
    .search-page-wrapper-result-filters vviinn-selected-filters {
      margin-top: 10px;
    }
    .search-page-wrapper-result-filters
      vviinn-selected-filters::part(selected-filters-list) {
      flex-wrap: wrap;
    }
  }

  .search-page-wrapper-result vviinn-results {
    --product-card-width: 215px;
  }

  @media screen and (max-width: 768px) {
    .search-page-wrapper-result vviinn-results {
      --product-card-width: 155px;
    }
  }
</style>

<div class="search-page-wrapper">
  <div class="search-page-wrapper-aside">
    <vviinn-cropper token="YOUR_READ_ONLY_TOKEN" width="300"></vviinn-cropper>
    <vviinn-extended-filters locale="en-US" mode="preview"></vviinn-extended-filters>
  </div>
  <div class="search-page-wrapper-result">
    <vviinn-text-search
      token="YOUR_READ_ONLY_TOKEN"
      locale="en-US"
      search-query="YOUR_SEARCH_QUERY"
      mode="extended"
    ></vviinn-text-search>
    <div class="search-page-wrapper-result-filters">
      <vviinn-extended-filters locale="en-US"></vviinn-extended-filters>
      <vviinn-selected-filters locale="en-US"></vviinn-selected-filters>
    </div>
    <vviinn-results
      token="YOUR_READ_ONLY_TOKEN"
      results-count="9"
      locale="en-US"
      one-click-discovery-mode="append-grid"
      product-details-new-tab="true"
    ></vviinn-results>
  </div>
</div>

In this basic example, we use vviinn-text-search, vviinn-results, and two variations of the filter component. Let’s take a closer look at the attributes we are using in this example:

The token attribute is required for all components (except filters) and is used to authenticate your requests.
The extended mode enables image search functionality.
The results-count attribute defines the number of results that will be fetched. It cannot exceed the number set in the Campaign settings.

Other attributes you can use are detailed on the components’ pages.

To see the filter columns, enable Filters in the Interface Controls section inside the Text Search campaign via the Panel. The Primary flag is responsible for showing filters in the vviinn-filters component.

Integration

To integrate the components into your project, install the vviinn-widgets package using one of the methods in the Installation section. You need at least version 2.76.1 of the package to use the components, but the latest version is recommended.

You can use the components in a framework-agnostic way or integrate them into your project with a specific framework. The components can be used together or separately, depending on your needs. They are highly customizable and suitable for a wide range of use cases.