Developer Guide
Product DocumentationDeveloper GuideAPI ReferenceHelp Center
  • Welcome!
  • Fundamentals
    • API and client libraries
      • REST API Reference
      • JavaScript
      • Node
      • PHP
      • Python
      • Ruby
      • .Net
    • Search UI widgets
      • Search results widget
      • Search input widget
      • Takeover Search Input Widget
      • Configuration Objects
    • Pipelines
      • Steps
      • Record Pipelines
      • Query pipelines
      • Fundamental steps
      • Variable manipulation
  • Guides
    • Quick Start
      • Setting up a collection
      • Tuning your search
    • Feature implementation
      • Implementing tracking
      • Promotion banners
      • Aggregate Filters
      • Bucket Aggregates
      • Redirects
    • Using pipelines
      • Configuring autocomplete
      • Configuring spelling
      • Phrase training
      • Regular expressions
  • Helpful links
    • Product Documentation
    • API Reference
    • Help Center
Powered by GitBook
On this page
  • Configuration
  • Filter
  • List
  • Color
  • Rating
  • Tabs
  • Select
  • Range
  • Search result options
  • Standard properties
  • Overlay properties

Was this helpful?

  1. Fundamentals
  2. Search UI widgets

Search results widget

PreviousSearch UI widgetsNextSearch input widget

Last updated 2 years ago

Was this helpful?

The search result widget displays search results to the user on a search result page. It contains the actual search results as well as filter, view options and pagination controls.

See the example in .

Configuration

The following options can be configured when creating the search results widget.

Name
Type
Default
Description

filters

_

options

[#search-result-options](search-results-widget.md#search-result-options "mention")

_

Specific configuration options.

Filter

The Filter object defines options to allow refining of search results. The options vary from a given type but all types share following basic properties:

Name
Type
Default
Description

name

string

_

The name of a given Filter.

title

string

_

Title of the filter.

type

'list'

Type of the filter.

List

Properties available for list filters.

Name
Type
Default
Description

field

string

_

A field in schema, used if count = true.

count

boolean

true if no options specified.

Map to a field which aims to perform a count aggregate.

options

object

_

Dictionary of name -> filter pairs, used if count = false.

multi

boolean

true

Multiple selections allowed.

array

boolean

false

Whether the response of the field is an array. This setting is only applicable if count is set.

group

string

false

limit

number

10

Maximum number of items to initially show. Maximum is 100.

searchable

boolean

true if the number of options exceeds limit.

If true, display an input for searching through items.

placeholder

string

'Search'

Placeholder for search input.

pinSelected

boolean

true if the number of options exceeds limit.

Pin selected items to the top of the list.

sort

'count' | 'alpha' | 'none'

'count'

How to sort the items. 'alpha' stands for 'alphanumeric' meaning to sort the items based on label alphabetically, 'count' to sort based on count, 'none' to skip the sorting process.

sortAscending

boolean

true if sort is not 'count'.

Whether to sort in ascending order.

format

'default' | 'price'

'default'

How to format the values.

hideCount

boolean

false

Hide total items count.

includes

string[]

_

Selected options will be displayed as filter options. Used if count = true.

excludes

string[]

_

Selected options will not be displayed as filter options. Used if count = true.

prefixFilter

string

_

If specified, only options that exactly match the prefix will be shown. The prefix will be removed from the option displayed. Used if count = true.

textTransform

'normal-case' | 'uppercase' | 'lowercase' | 'capitalize' | 'capitalize-first-letter'

'normal-case'

Control the capitalization of text options.

{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE"
}

By default, it will perform a count aggregate over the field brand to return a list of filter options. The list can be filtered via includes, excludes or prefixFilter.

However, we can manually specify the options:

{
  "name": "NAME",
  "count": false,
  "title": "TITLE",
  "multi": false,
  "hideCount": true,
  "options": {
    "Appliances": "level1 ~ 'appliances'",
    "Audio": "level1 ~ 'audio'",
    "Cell phones": "level1 ~ 'Cell Phones'",
    "Video games": "level1 ~ 'Video games'"
  }
}

Color

The color filter does not support any custom properties.

{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "color"
}

Rating

Properties available for rating filters.

Name
Type
Default
Description

hideCount

boolean

false

Hide total items count.

{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "rating"
}

Tabs

Properties available for tabs filters.

Name
Type
Default
Description

field

string

_

A field in schema, used if count = true.

count

boolean

true if no options specified.

Map to a field which aims to perform a count aggregate.

options

object

_

Dictionary of name -> filter pairs.

multi

boolean

true

Multiple selections allowed.

array

boolean

false

Whether the response of the field is an array. This setting is only applicable if count is set.

group

string

false

limit

number

10

Maximum number of items to initially show. Maximum is 100.

sort

'count' | 'alpha' | 'none'

'count'

How to sort the items. 'alpha' stands for 'alphanumeric' meaning to sort the items based on label alphabetically, 'count' to sort based on count, 'none' to skip the sorting process.

sortAscending

boolean

true if sort is not 'count'.

Whether to sort in ascending order.

format

'default' | 'price'

'default'

How to format the values.

hideCount

boolean

false

Hide total items count.

includes

string[]

_

Selected options will be displayed as filter options. Used if count = true.

excludes

string[]

_

Selected options will not be displayed as filter options. Used if count = true.

prefixFilter

string

_

If specified, only options that exactly match the prefix will be shown. The prefix will be removed from the option displayed. Used if count = true.

textTransform

'normal-case' | 'uppercase' | 'lowercase' | 'capitalize' | 'capitalize-first-letter'

'normal-case'

Control the capitalization of text options.

{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "tabs"
}

Select

Properties available for select filters.

Name
Type
Default
Description

field

string

_

A field in schema, used if count = true.

count

boolean

true if no options specified.

Map to a field which aims to perform a count aggregate.

options

object

_

Dictionary of name -> filter pairs.

multi

boolean

true

Multiple selections allowed.

array

boolean

false

Whether the response of the field is an array. This setting is only applicable if count is set.

group

string

false

limit

number

10

Maximum number of items to initially show. Maximum is 100.

sort

'count' | 'alpha' | 'none'

'count'

How to sort the items. 'alpha' stands for 'alphanumeric' meaning to sort the items based on label alphabetically, 'count' to sort based on count, 'none' to skip the sorting process.

sortAscending

boolean

true if sort is not 'count'.

Whether to sort in ascending order.

format

'default' | 'price'

'default'

How to format the values.

hideCount

boolean

false

Hide total items count.

includes

string[]

_

Selected options will be displayed as filter options. Used if count = true.

excludes

string[]

_

Selected options will not be displayed as filter options. Used if count = true.

prefixFilter

string

_

If specified, only options that exactly match the prefix will be shown. The prefix will be removed from the option displayed. Used if count = true.

textTransform

'normal-case' | 'uppercase' | 'lowercase' | 'capitalize' | 'capitalize-first-letter'

'normal-case'

Control the capitalization of text options.

{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "select"
}

Range

Properties available for range filters.

Name
Type
Default
Description

field

string

_

A field in schema, used if count = true.

group

string

false

initial

[number, number]

_

The initial value.

aggregate

boolean

true

If true, set value for min and max from the backend response.

min

number

0

The min value of the filter.

max

number

aggregate ? 0 : 100

The max value of the filter.

format

'default' | 'price'

'default'

How to format the values.

showInputs

boolean

false

Show inputs.

steps

number

_

An array of custom steps to use. This will override step.

tick

number

_

The interval to show small ticks.

ticks

number[]

_

An array of custom ticks to use. This will override tick.

By default, the max and min value are set from an aggregation operation. However, we can manually define the min-max range and the initial value.

{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "range",
  "aggregate": false,
  "min": 0,
  "max": 2000,
  "initial": [200, 500]
}

Search result options

Name
Type
Default
Description

showViewType

true

Set to true or false to toggle the display of the View (grid or list) selector

resultsPerPage

ResultsPerPageProps

{options: [15, 25, 50, 100]}

sorting

SortingProps

_

input

`InputProps & {hide: boolean, position: 'top' \

'aside'}`

{mode: 'instant', position: 'aside'}

results

ResultsProps

{imageAspectRatio: {grid: 1, list: 1}, imageObjectFit: {grid: 'cover', list: 'container'}}

pagination

PaginationProps

_

mode

'standard'

Control the display of the search results. While the standard mode is for displaying the search results on a page content, the overlay mode places the search results in the middle of an overlay screen.

Standard properties

Exclusive props if mode is standard.

Name
Type
Default
Description

'syncURL'

'none' | 'replace' | 'push'

'push'

Keep the search state in the URL if the option is not none. While replace prevent adding a new URL entry into the history stack, push will do the opposite.

urlParams

{q: string}

{q: 'q'}

A key -> value pair object maps the URL params to initial values for the search. q defines the URL param for the initial search query.

<div data-widget="search-results">
  <script type="application/json">
    {
      "account": "1594153711901724220",
      "collection": "bestbuy",
      "pipeline": "query",
      "fields": {
        "title": "name",
        "subtitle": "brand",
        "url": "https://www.bestbuy.com/products/${id}"
      },
      "filters": [
        {
          "name": "brand",
          "field": "brand",
          "title": "Brand",
          "searchable": true
        },
        {
          "name": "category",
          "field": "level1",
          "title": "Category",
          "searchable": true
        },
        {
          "name": "color",
          "field": "imageTags",
          "title": "Color",
          "type": "color"
        },
        {
          "name": "rating",
          "field": "rating",
          "title": "Rating",
          "type": "rating"
        },
        {
          "name": "price",
          "field": "price",
          "title": "Price",
          "type": "range"
        }
      ]
    }
  </script>
</div>
<script async src="https://cdn.search.io/embed/1/loader.js"></script>

Overlay properties

Exclusive props if mode is overlay.

Name
Type
Default
Description

buttonSelector

string | string[]

['form[action="/search"]', 'a[href="/search"]'] if preset is 'shopify'

A single or a list of CSS selector of elements used to trigger the overlay dialog to open.

inputSelector

string

_

If defined, it will take the current value of the input to be the inital search query after the overlay dialog is open.

ariaLabel

string

'Open search'

ARIA label for the buttonSelector element.

modal

ModalProps

_

<div data-widget="overlay">
  <script type="application/json">
    {
      "account": "1594153711901724220",
      "collection": "bestbuy",
      "pipeline": "query",
      "fields": {
        "title": "name",
        "subtitle": "brand",
        "url": "https://www.bestbuy.com/products/${id}"
      },
      "filters": [
        {
          "name": "brand",
          "field": "brand",
          "title": "Brand",
          "searchable": true
        },
        {
          "name": "category",
          "field": "level1",
          "title": "Category",
          "searchable": true
        },
        {
          "name": "color",
          "field": "imageTags",
          "title": "Color",
          "type": "color"
        },
        {
          "name": "rating",
          "field": "rating",
          "title": "Rating",
          "type": "rating"
        },
        {
          "name": "price",
          "field": "price",
          "title": "Price",
          "type": "range"
        }
      ],
      "options": {
        "mode": "overlay",
        "buttonSelector": "#button"
      }
    }
  </script>
</div>
<script async src="https://cdn.search.io/embed/1/loader.js"></script>

Define a list of active filters. The configuration is specified as an array of properties.

| | | | |

A group name, for grouping multiple filters together using

See the example in .

A group name, for grouping multiple filters together using

See the example in .

A group name, for grouping multiple filters together using

See the example in .

A group name, for grouping multiple filters together using

See the example in .

Options of ResultsPerPage component used to capture user input for how many results displayed per page. See .

Options of Sorting component used to capture user input on how to sort search results. See .

Options of Results component displaying result response from a search query. See .

Options of Pagination component allowing the user to change the current page. See .

|

See the example in .

Options for the dialog window holding the search results interface. See .

See the example in .

Codesandbox
Codesandbox
Codesandbox
Codesandbox
Codesandbox
Codesandbox
ARRAY_MATCH
ARRAY_MATCH
ARRAY_MATCH
ResultsPerPage props
Sorting props
Results props
Pagination props
'standard'
'overlay'
Modal props
Filter[]
Filter
'list'
'color'
'rating'
'tabs'
'select'
'range'
ARRAY_MATCH
Codesandbox
Search result widget