Search results widget

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 Codesandbox.

Configuration

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

Name	Type	Default	Description
filters	Filter[]	_	Define a list of active filters. The configuration is specified as an array of Filter properties.
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' | 'color' | 'rating' | 'tabs' | 'select' | 'range'	'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	A group name, for grouping multiple filters together using ARRAY_MATCH
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'"
  }
}

See the example in Codesandbox.

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	A group name, for grouping multiple filters together using ARRAY_MATCH
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"
}

See the example in Codesandbox.

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	A group name, for grouping multiple filters together using ARRAY_MATCH
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"
}

See the example in Codesandbox.

Range

Properties available for range filters.

Name	Type	Default	Description
field	string	_	A field in schema, used if count = true.
group	string	false	A group name, for grouping multiple filters together using ARRAY_MATCH
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]
}

See the example in Codesandbox.

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]}	Options of ResultsPerPage component used to capture user input for how many results displayed per page. See ResultsPerPage props.
sorting	SortingProps	_	Options of Sorting component used to capture user input on how to sort search results. See Sorting props.
input	`InputProps & {hide: boolean, position: 'top' \	'aside'}`	{mode: 'instant', position: 'aside'}
results	ResultsProps	{imageAspectRatio: {grid: 1, list: 1}, imageObjectFit: {grid: 'cover', list: 'container'}}	Options of Results component displaying result response from a search query. See Results props.
pagination	PaginationProps	_	Options of Pagination component allowing the user to change the current page. See Pagination props.
mode	'standard' | 'overlay'	'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>

See the example in Codesandbox.

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	_	Options for the dialog window holding the search results interface. See Modal props.

<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>

See the example in Codesandbox.