# 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](https://codesandbox.io/s/overlay-mode-search-results-widget-unv1n).
## Configuration
The following options can be configured when creating the search results widget.
| Name | Type | Default | Description |
| --------- | ------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| `filters` | [`Filter[]`](#filter) | `_` | Define a list of active filters. The configuration is specified as an array of [Filter](#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'`](#list) \| [`'color'`](#color) \| [`'rating'`](#rating) \| [`'tabs'`](#tabs) \| [`'select'`](#select) \| [`'range'`](#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](https://docs.search.io/documentation/fundamentals/filter-expressions#handling-sub-variants) |
| `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. |
```json
{
"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:
```json
{
"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](https://codesandbox.io/s/list-filter-87xhw).
### **Color**
The color filter does not support any custom properties.
```json
{
"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. |
```json
{
"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](https://docs.search.io/documentation/fundamentals/filter-expressions#handling-sub-variants) |
| `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. |
```json
{
"name": "NAME",
"field": "FIELD_NAME",
"title": "TITLE",
"type": "tabs"
}
```
See the example in [Codesandbox](https://codesandbox.io/s/tabs-filter-b4qom).
### **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](#configuration) |
| `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. |
```json
{
"name": "NAME",
"field": "FIELD_NAME",
"title": "TITLE",
"type": "select"
}
```
See the example in [Codesandbox](https://codesandbox.io/s/select-filter-2egs3).
### **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](https://docs.search.io/documentation/fundamentals/filter-expressions#handling-sub-variants) |
| `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.
```json
{
"name": "NAME",
"field": "FIELD_NAME",
"title": "TITLE",
"type": "range",
"aggregate": false,
"min": 0,
"max": 2000,
"initial": [200, 500]
}
```
See the example in [Codesandbox](https://codesandbox.io/s/range-filter-ctbvf).
## 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](https://react.docs.search.io/search-ui/resultsperpage#props). |
| `sorting` | `SortingProps` | `_` | Options of Sorting component used to capture user input on how to sort search results. See [Sorting props](https://react.docs.search.io/search-ui/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](https://react.docs.search.io/search-ui/results#props). |
| `pagination` | `PaginationProps` | `_` | Options of Pagination component allowing the user to change the current page. See [Pagination props](https://react.docs.search.io/components/pagination#props). |
| `mode` | [`'standard'`](http://localhost:8000/developer-guide/widget/#standard-properties) \| [`'overlay'`](http://localhost:8000/developer-guide/widget/#overlay-properties) | `'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. |
```html
```
See the example in [Codesandbox](https://codesandbox.io/s/standard-mode-search-results-widget-shgnj).
### **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](https://react.docs.search.io/components/modal#props). |
```html
```
See the example in [Codesandbox](https://codesandbox.io/s/overlay-mode-search-results-widget-unv1n).