Integrating Search

Sajari Search Widget

Search widgets are discrete blocks of JSON code that utilize the Sajari React SDK to render a variety of search widgets for your website. You can use the Search UI Builder in the Sajari admin console to generate a Search Widget to embed in your website.

The following configuration properties are available to customize the widget:

NameTypeDefaultDescription
pipelinestring (required)_The pipeline configuration. See Pipeline overview.
accountstring (required)_The account configuration (available in the credentials section in the Sajari admin interface).
collectionstring (required)_The collection to query (available in the credentials section in the Sajari admin interface).
endpointstring'//jsonapi.sajari.net'The endpoint configuration.
preset'shopify' | 'website' | ''''The collection template. The set value affects the default values of properties such as buttonSelector.
tracking'click' | 'posneg''click'Enable tracking to give you insights into the search behavior of your users and how your content is performing.
variablesVariables_Define simple key -> value pair object used for every search request. The configuration is specified as Variables properties.
configConfig_Defines mapping between key/value pair params to be sent with each and every request .The configuration is specified as Config properties.
fieldsFieldDictionary_Map fields in your data to the required fields to display in the UI. The configuration is specified as FieldDictionary properties.
defaultFilterstring_A default filter to apply to all search requests.
currencystring'USD'The currency code to use for any formatted price values.
themeTheme_Set basic color options for the interface. The configuration is specified as Theme properties.
customClassNamesobject_Add CSS class names to components. See Available className.
disableDefaultStylesbooleanfalseDisable the default styles of components.
importantStylesbooleantrueAdd !important to the provided styles to override any CSS clashes that usually result in strange styling.

The above configuration properties are defined based on the following structure:

<div data-widget="widget-name">
  <script type="application/json">
    {
      "account": "ACCOUNT_ID",
      "collection": "COLLECTION_ID",
      "pipeline": "PIPELINE_NAME",
      ...
    }
  </script>
</div>
<script async src="https://cdn.sajari.com/embed/1/loader.js"></script>

Search Results Widget

The search result widget displays search results to the user on a search result page. The following options can be configured when creating the search results widget.

NameTypeDefaultDescription
filtersFilter[]_Define a list of active filters. The configuration is specified as an array of Filter properties.
optionsSearchResultsOptions_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:

NameTypeDefaultDescription
namestring_The name of a given Filter.
titlestring_Title of the filter.
type'list' | 'color' | 'rating' | 'tabs' | 'select' | 'range''list'Type of the filter.

List properties

Exclusive props if type is list.

NameTypeDefaultDescription
fieldstring_A field in schema, used if count = true.
countbooleantrue if no options specified.Map to a field which aims to perform a count aggregate.
optionsobject_Dictionary of name -> filter pairs, used if count = false.
multibooleantrueMultiple selections allowed.
arraybooleanfalseWhether the response of the field is an array. This setting is only applicable if count is set.
groupstringfalseA group name, for grouping multiple filters together using ARRAY_MATCH
limitnumber10Maximum number of items to initially show. Maximum is 100.
searchablebooleantrue if the number of options exceeds limit.If true, display an input for searching through items.
placeholderstring'Search'Placeholder for search input.
pinSelectedbooleantrue 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.
sortAscendingbooleantrue if sort is not 'count'.Whether to sort in ascending order.
format'default' | 'price''default'How to format the values.
hideCountbooleanfalseHide total items count.
includesstring[]_Selected options will be displayed as filter options. Used if count = true.
excludesstring[]_Selected options will not be displayed as filter options. Used if count = true.
prefixFilterstring_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.
Click to expand example
{
  "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 properties

Exclusive props if type is color.

NameTypeDefaultDescription
Click to expand example
{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "color"
}

See the example in Codesandbox.

Rating properties

Exclusive props if type is rating.

NameTypeDefaultDescription
hideCountbooleanfalseHide total items count.
Click to expand example
{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "rating"
}

See the example in Codesandbox.

Tabs properties

Exclusive props if type is tabs.

NameTypeDefaultDescription
fieldstring_A field in schema, used if count = true.
countbooleantrue if no options specified.Map to a field which aims to perform a count aggregate.
optionsobject_Dictionary of name -> filter pairs.
multibooleantrueMultiple selections allowed.
arraybooleanfalseWhether the response of the field is an array. This setting is only applicable if count is set.
groupstringfalseA group name, for grouping multiple filters together using ARRAY_MATCH
limitnumber10Maximum 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.
sortAscendingbooleantrue if sort is not 'count'.Whether to sort in ascending order.
format'default' | 'price''default'How to format the values.
hideCountbooleanfalseHide total items count.
includesstring[]_Selected options will be displayed as filter options. Used if count = true.
excludesstring[]_Selected options will not be displayed as filter options. Used if count = true.
prefixFilterstring_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.
Click to expand example
{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "tabs"
}

See the example in Codesandbox.

Select properties

Exclusive props if type is select.

NameTypeDefaultDescription
fieldstring_A field in schema, used if count = true.
countbooleantrue if no options specified.Map to a field which aims to perform a count aggregate.
optionsobject_Dictionary of name -> filter pairs.
multibooleantrueMultiple selections allowed.
arraybooleanfalseWhether the response of the field is an array. This setting is only applicable if count is set.
groupstringfalseA group name, for grouping multiple filters together using ARRAY_MATCH
limitnumber10Maximum 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.
sortAscendingbooleantrue if sort is not 'count'.Whether to sort in ascending order.
format'default' | 'price''default'How to format the values.
hideCountbooleanfalseHide total items count.
includesstring[]_Selected options will be displayed as filter options. Used if count = true.
excludesstring[]_Selected options will not be displayed as filter options. Used if count = true.
prefixFilterstring_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.
Click to expand example
{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "select"
}

See the example in Codesandbox.

Range properties

Exclusive props if type is range.

NameTypeDefaultDescription
fieldstring_A field in schema, used if count = true.
groupstringfalseA group name, for grouping multiple filters together using ARRAY_MATCH
initial[number, number]_The initial value.
aggregatebooleantrueIf true, set value for min and max from the backend response.
minnumber0The min value of the filter.
maxnumberaggregate ? 0 : 100The max value of the filter.
format'default' | 'price''default'How to format the values.
showInputsbooleanfalseShow inputs.
stepsnumber_An array of custom steps to use. This will override step.
ticknumber_The interval to show small ticks.
ticksnumber[]_An array of custom ticks to use. This will override tick.
Click to expand example
{
  "name": "NAME",
  "field": "FIELD_NAME",
  "title": "TITLE",
  "type": "range"
}

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

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

See the example in Codesandbox.

SearchResultsOptions

NameTypeDefaultDescription
resultsPerPageResultsPerPageProps{options: [15, 25, 50, 100]}Options of ResultsPerPage component used to capture user input for how many results displayed per page. See ResultsPerPage props.
sortingSortingProps_Options of Sorting component used to capture user input on how to sort search results. See Sorting props.
inputInputProps & {hide: boolean, position: 'top' \| 'aside'}{mode: 'instant', position: 'aside'}Options of Input component used to capture query input via a text field. It can also provide suggestions, typeahead and instant search modes. See Input props
resultsResultsProps{imageAspectRatio: {grid: 1, list: 1}, imageObjectFit: {grid: 'cover', list: 'container'}}Options of Results component displaying result response from a search query. See Results props.
paginationPaginationProps_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.

NameTypeDefaultDescription
'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.
Click to expand example
<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.sajari.com/embed/1/loader.js"></script>

See the example in Codesandbox.

Overlay properties

Exclusive props if mode is overlay.

NameTypeDefaultDescription
buttonSelectorstring | 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.
inputSelectorstring_If defined, it will take the current value of the input to be the inital search query after the overlay dialog is open.
ariaLabelstring'Open search'ARIA label for the buttonSelector element.
modalModalProps_Options for the dialog window holding the search results interface. See Modal props.
Click to expand example
<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.sajari.com/embed/1/loader.js"></script>

See the example in Codesandbox.

Takeover Search Input Widget

The Takeover Search Input widget allows users to inject Sajari search experience into the existing input while keeping the current appearance. The following options can be configured when creating the Takeover Search Input widget.

NameTypeDefaultDescription
selectorstring'form[action="/search"] input[name="q"]' if the preset is 'shopify'The CSS selector of the input being taken over.
mode'standard' | 'typeahead' | 'suggestions' | 'results''results'The mode of the input. For details, see Input props.
omittedElementSelectorsstring | string[]_A single or a list of CSS selector of elements to be removed when the widget has mounted.
Click to expand example
<div data-widget="search-input-binding">
  <script type="application/json">
    {
      "account": "1594153711901724220",
      "collection": "bestbuy",
      "pipeline": "query",
      "selector": "#search-input",
      "mode": "results"
    }
  </script>
</div>
<script async src="https://cdn.sajari.com/embed/1/loader.js"></script>

See the example in Codesandbox.

Search Input Widget

The search input widget is typically used in a global template and positioned in the header of the page. It renders a search input field. The following options can be configured when creating the Search Input Widget.

NameTypeDefaultDescription
mode'standard' | 'typeahead' | 'suggestions' | 'results''suggestions'The mode of the input. For details, see Input props.
redirect{url: string, queryParamName: string}{url: 'search', queryParamName: 'q'}Options to set the redirect URL and the name of the search query param, normally, the destination is where the Search Results Widget is located.
Click to expand example
<div data-widget="search-input">
  <script type="application/json">
    {
      "account": "1594153711901724220",
      "collection": "bestbuy",
      "pipeline": "query",
      "selector": "#search-input",
      "mode": "suggestions",
      "redirect": {
        "url": "search.html",
        "queryParamName": "q"
      }
    }
  </script>
</div>
<script async src="https://cdn.sajari.com/embed/1/loader.js"></script>

See the example in Codesandbox.

Common Config Objects

Variables

The Variables is a simple key -> value pair object used for every search request. The proprties will vary based on your pipeline configuration but the most common implementations will use the following:

Value types can be string | string[] | number | boolean.

NameTypeDefaultDescription
qstring_The search query.
q.overridestring_
q.suggestionsstring_The autocomplete options for the search query.
filterstring'_id != ""'Default filter to apply.
resultsPerPagenumber15How many results to display per page.
pagenumber1Which page to display.
maxSuggestionsnumber10How many autocomplete suggestions per search.

Config

The Config object defines mapping between key/value pair params to be sent with each and every request.

NameTypeDefaultDescription
qParamstring'q'The key that includes a search query.
qOverrideParamstring'q.override'
qSuggestionsParamstring'q.suggestions'The key that includes autocomplete options for the search query.
resultsPerPageParamstring'resultsPerPage'The key for how many results to display per page.
pageParamstring'page'The key for which page to display.
maxSuggestionsnumber'maxSuggestions'The key for how many autocomplete suggestions per search.

FieldDictionary

The FieldDictionary object is used to map fields in your data to the required fields to display in the UI. By default, the fields for a website search collection are used.

NameTypeDefaultDescription
idstring'_id'Unique identifier for the record.
urlstring'url'URL for the record, required for links in results.
titlestring'title'The main title for the result.
subtitlestring'url'The subtitle. Often a brand, category, or the URL.
descriptionstring'description'A description to display beneath the title and subtitle.
imagestring'image'An image, if applicable.
pricestring'price'A price, if applicable.
originalPricestring'originalPrice'An original price, if applicable. If the value is more than price (or it's index if price & originalPrice are both arrays) then the original price will be displayed (with strikethrough) and the current price highlighted in red.
ratingstring'rating'A rating, if applicable.

Theme

The Theme object is used to set basic color options for the UI. Currently this is only for the primary actions.

NameTypeDefaultDescription
colors{primary: {base: string, text: string, active: string}}_Set colors for primary actions.