Installation

How to install Site Search 360 on your site

Copy and paste the following script to your site right before the </body> tag and you're set. More advanced configuration options can be applied later (see below). Remember to change 'mysiteid' to your own Site ID (displayed in your Profile).

If you're using a site platform where you can't access your site's or your site template's source code, try adding a code block element instead.

<script>
   /* Create a configuration object */
   var ss360Config = {
      /* Your Site ID that usually equals the domain you signed up with */
      siteId: 'mysiteid',
      /* A CSS selector that points to your search box */
      searchBox: {selector: '#searchBox'},
   };
</script>
<script src="https://cdn.sitesearch360.com/v13/sitesearch360-v13.min.js" async></script>

Make sure you have an <input> box on your site and that searchBox.selector is a CSS selector that points to that input.

If you don't have a search box on your site yet, you can insert the following code snippet wherever you want the box and search button to be displayed on your site - for example, in your site header:

<section role="search" data-ss360="true">
   <input type="search" id="searchBox" placeholder="Search…">
   <button id="searchButton"></button>
</section>

Please note: this documentation page refers to our latest search script (v13). For the installation and configuration instructions for v12 and older script versions, please visit this page.

Configuration Options

Connect SS360 to your search button

If you have a search button, you need to bind it in the searchBox configuration by providing the CSS selector of your searchButton like this:

<script>
var ss360Config = {
   siteId: 'mysiteid',
   searchBox: {
      selector: '#searchBox',
      searchButton: '#searchButton' /* Search button CSS selector */
   }
};
</script>
<script src="https://cdn.sitesearch360.com/v13/sitesearch360-v13.min.js" async></script>

Customize your search layout colors

You can quickly adjust the main color used throughout your search result elements to make them match your website's color palette. For example, if you like Coca-Cola-style red, use the #ed1c16 hex code under ss360Config.style.accentColor:

<script>
var ss360Config = {
   siteId: 'mysiteid',
   searchBox: {
      selector: '#searchBox',
      searchButton: '#searchButton'
   },
   style: {
      accentColor: "#ed1c16",
      themeColor: "#808080"
   }
};
</script>
<script src="https://cdn.sitesearch360.com/v13/sitesearch360-v13.min.js" async></script>

accentColor modifies the color of your Site Search 360 search button, result titles, 'See More' results, hover effects, etc. - basically, of all clickable elements.

themeColor is less noticeable and used with non-interactive elements so it's usually more fitting to use a calming shade, e.g., from a grayscale color palette.

Advanced Configuration

There are many options that help you configure and customize the search experience. Here is a complete list of configuration parameters.

Read the inline comments to learn how to use the parameters.

<script>
// create a settings object
var ss360Config = {
   showErrors: false, // shows implementation errors if set to true
   allowCookies: true, // whether to allow the SS360 search script to set cookies
   language: 'en', // search interface language, available options: 'en', 'de', 'fr', 'nl', 'pl', 'it', 'es', 'mx', 'tr', 'pt'
   // suggestions are top matching results or suggested search queries shown in a dropdown below the search box
   suggestions: {
      show: true, // set to false to disable search suggestions
      showImages: true, // show images in search suggestions
      linksOpenNewTab: false, // set to true to force suggested results to open in a new tab
      num: 6, // max. number of search suggestions to be shown
      minChars: 3, // min. number of characters typed in the search box to trigger suggestions, default: 3
      highlight: true, // whether matched words should be highlighted, default: true
      throttleTime: 300, // milliseconds until suggestions are triggered after user stops typing, default: 300ms
      maxWidth: 'auto', // max. width of the suggest box, default: as wide as the input box, at least 275px
      showOnMobile: true, // whether to show search suggestions on mobile devices (less than 768px), disables specialMobileSuggestions if set to false, default: true
      mobileScrollOnFocus: true, // whether to scroll the page in order for the search box to be to the top of the window (on screens below 768 px)

      // query suggestion settings (clicking on a suggested query term triggers full search results for the query)
      maxQuerySuggestions: 3, // the maximum number of query suggestions
      querySuggestionHeadline: undefined, // the headline of the query suggestions, e.g. 'Try searching for...', by default no headline is shown
      emptyQuerySuggestions: undefined, // suggestions to be shown when the search box gets focus but user hasn't started typing a query, e.g. suggests:{_:[{name:"The Title",link:"https://mylink.com/",image:"https://placekitten.com/150/150"}]}

      // additional information to be shown in search suggestions
      searchHistoryLabel: 'You recently searched for', // the headline for search queries recently entered by user, displayed on empty search box focus
      maxSearchHistoryEntries: 5, // max. number of recent queries to display, set to 0 to disable search history. If emptyQuerySuggestions is defined, search history gets disabled
      viewAllLabel: undefined, // the label of a 'View All' button shown below the suggestion list, by default no button is added
      groupCta: {
         show: false, // whether to show call-to-action buttons for each content group in search suggestions, e.g. 'View all blog articles'
         label: 'View all #GROUP# results', // the default label of the CTA, #GROUP# is replaced with the content group name
         groupLabels: {}, // custom CTA labels for your content groups, e.g. {Blog: 'Let\'s check out the blog', _: 'Show everything else'}. If groupLabels aren't specified, the default label is used. Set to null to disable the group CTA, e.g. {_: null} to show no CTA under uncategorized/Other suggestions
         callback: undefined, // the CTA click callback, by default the search results are shown and the selected content group is opened
         lowerCaseNames: false // whether to lowercase the content group names in the default CTA labels
      },
      maxSuggestions: undefined, // to set a max. number of suggestions to show per content group, e.g. {Products: 5, Blog: 1}. NB: specify the limits for ALL content groups that should be displayed in suggestions, unset groups won't be shown (this overrides contentGroups.include and data-ss360-include)
      dataPoints: undefined, // to use data points in suggestions, this overrides the deprecated extraHtml setting, e.g. {price: {html: '#Price# $', position: 1}, category: {html: '#Category#', position: 2}}
      suggestTemplate: {
         template: undefined,
         preRenderCallback: undefined,
         templateBuiltCallback: undefined,
         postRenderCallback: undefined
      },

      // other search suggestion settings
      triggersSearch: false, // set to true to skip suggestions and trigger full search results as user types, throttleTime lets you adjust how quickly results should be displayed
      equalSearch: false, // set to true if suggestions should be equal to full search results (NB: suggestions aren't counted against the search volume quota while results are)
      forceBelow: false, // set to true if you want to always display suggestions below the search box
      viewKeyMappings: undefined, // used to map things like the 'Other' content group _ to a human readable name, e.g. set by the otherName parameter
      selectionOrder: [] // if you heavily style your suggestions, e.g. display them in columns rather than a list, and the arrow key order is different from the order in the UI, you can set selectionOrder = ['Products', 'Blog'] so that the arrow keys always start with 'Products'
   },
   style: {
      themeColor: '#4a4f62', // affects border color of content group tabs and filter buttons
      accentColor: '#3d8fff', // affects all clickable elements: search result titles, search buttons, 'See more' button, active filters, tab color on hover
      suggestions: undefined, // check Search Designer for customization examples
      defaultCss: true, // whether to include the default CSS,
      searchBox: undefined, // check Search Designer for customization examples
      loaderType: 'skeleton', // can be 'circle', 'square', or 'skeleton'
      animationSpeed: 250, // loading animation speed in milliseconds
      additionalCss: undefined, // custom CSS to add to the plugin's stylesheets, has to be minified e.g. '#ss360-layer{background: red;}'
      redrawTrigger: undefined // a CSS selector to an element which triggers redrawing of the applied styles
   },
   searchBox: {
      placeholder: undefined,
      autofocus: false, // if true, the search box gets focus after initialization
      selector: '#searchBox', // the selector to the search box
      searchButton: '#searchButton', // CSS selector of search buttons
      focusLayer: false, // if true, a layer is shown when the user focuses on the search input
      preventFormParentSubmit: true, // whether to disable submitting of parenting form
      searchButtonLabel: undefined // the label of the search button in Site Search 360 custom search inputs, if not set, a magnifying glass icon is rendered
   },
   results: {
      // embedding search results into your site page rather than showing them in a layover modal (default)
      embedConfig: undefined, // {
      //   'url': undefined,
      //   'contentBlock':'.page-content-body'
      // }, // if url is given, user is redirected to that page and results are inserted into the specified content block
      showSearchBoxEmbed: false, // whether to show search box in search result block for embed search results
      semanticMode: false, // whether to generate semantic URLs like /s-t-shirts, only to be used with embed mode
      semanticModeParamName: 's-', // the search query prefix in semantic mode

      // to open a full screen search page when user clicks on a search icon/button
      fullScreenConfig: undefined, 
      // {
      //   trigger: '#ss360-search-trigger',
      //   caption: 'Search this site',
      //   transition: 'fade'
      // }, // trigger is the CSS selector to the search icon/button, caption is displayed on top of the layover page

      // layover implementation settings
      showSearchBoxLayover: true, // whether to show a search box inside the search result layover
      layoverTrigger: undefined, // a CSS selector that points to an element which should open the layover search modal
      hideLayerOnBodyClick: true, // whether to hide the search result layover when user clicks outside of the layer (otherwise only the ESC key and close button click hides the layover layer)

      // general result snippet settings
      group: true, // if content groups are set up, results are grouped and split into tabs
      showContentGroupHeadings: true, // whether to show the content group names/headings, if navigation.type is set to tabs, headings are visible for screen readers only
      limitPerGroup: true, // if set to true, the maximum number of search results is applied to every single content group, otherwise the limit is spread across all groups, default: true
      num: 999999, // the maximum number of search results to be returned
      moreResultsPagingSize: 12, // how many results to show per result page, 'See More' button loading the next page, max: 24
      infiniteScroll: false, // set it to true to show more results as soon as user scrolls to the end of the result block (it only works if navigation.type is 'tabs' or if only one content group has been retrieved)
      searchQueryParamName: 'ss360Query', // the name of the search query parameter
      linksOpenNewTab: false, // whether clicking on the result link should open a new tab/window
      redirectOnSingle: false, // whether to redirect to the only result page instead of showing the result
      
      // sorting and filters
      sorting: undefined, // the default sorting option to apply when data points are set up
      filters: undefined, // sets an initial value to the filter, it's not query-specific, e.g. [{"name":"Tags","key":"fid#8","values":[{"name":"vegetarian"}]}]
      nameParsing: true, // sorting options are added to the result page URL as query parameters, e.g. ?ss360Query=recipe&tags=vegetarian
      sortingParamName: 'ss360Sorting', // the default sorting query parameter name in the URL

      // to customize search interface labels and captions; for EN/DE/FR/NL the UI can be auto-translated with the ss360Config.language setting
      caption: 'Found #COUNT# search results for "#QUERY#"', // the caption above the search results
      moreResultsButton: 'See more', // HTML for the more results button, all results are shown if set to null
      noResultsText: 'Sorry, we have not found any matches for your query.', // the text to show when no results are found
      noResultsRedirect: undefined, // the full URL to redirect to when no results are found, e.g. 'https://mysite.com/no-results'
      queryCorrectionText: 'Did you mean "#CORRECTION#"?', // #CORRECTION# is automatically replaced by the corrected query if the Spelling Correction setting is on
      queryCorrectionRewrite: 'Showing results for "#CORRECTION#"', // #CORRECTION## is replaced automatically with the rewritten/corrected query
      orderByRelevanceText: 'Relevance', // the text for the 'order by relevance' sorting option
      sortingLabel: 'Sorting:', // a text label next to the sorting dropdown menu
      
      // result image settings
      lazyLoadImages: true, // to lazy-load images as user scrolls through results instead of loading them all at once
      placeholderImage: undefined, // set to null to collapse all missing images or add a URL for a placeholder graphic, e.g. 'https://placekitten.com/200/300'
      hideResultsWithoutImage: false, // whether to hide all results that don't have any image or have a broken image
      checkImageQuality: true, // set to false to allow large aspect ratio images

      // adding call-to-action buttons to result snippets
      cta: [ // array of CTAs to render in the search results, every CTA is an object with the following structure: //
            {
         text: 'The text of the CTA Button', 
         link: 'The link to redirect to after the CTA is clicked', // (default: no redirect), use #RESULT_URL# to redirect to the result page
         renderAsButton: true, // whether to render the CTA as a button, default: true
         icon: 'ss360:arrow', // icon to show inside of the CTA button ('ss360:arrow' - triangle arrow, 'ss360:shopping-cart' - shopping cart icon, svg string, image URL, or 'none'), default: 'ss360:arrow', only rendered if renderAsButton is true
         clickCallback: undefined, // a callback to call after the CTA button is clicked, receives the event object and result JSON as parameter
         includeContentGroups: undefined, // JSON array of content group names for which the CTA should be shown //,
         excludeContentGroups: undefined, // JSON array of content group names for which the CTA should be hidden //,
         position: 'left' // the alignment of the CTA button, 'left', 'center' or 'right' - works only for ctaDirection: 'column'; for ctaDirection: 'row' all CTAs are aligned based on the first item in the list  //
         }
      ],
      ctaDirection: 'column', // how to place multiple CTAs within search result - 'row' vs 'column' (default)
      
      resultTemplate: {
         template: undefined,
         preRenderCallback: undefined,
         templateBuiltCallback: undefined,
         postRenderCallback: undefined
      }
   },
   queryTerm: {
      scrollIntoViewBlock: 'start', // how to scroll the text into view on redirect and a single query term match, one of 'start', 'center', 'end' or 'none' (don't scroll into view at all)
      highlightContext: undefined, // a CSS selector to limit a part of the page where redirect query terms are highlighted
      highlight: true, // whether to highlight search terms within result page content (once user selects a result)
      highlightMatchedContent: false, // whether to highlight content that fully matches user query within result page content (once user selects a result)
      scrollOnMultiMatch: false, // whether to scroll to the matched content even if it occurs multiple times on the page
      tokenize: false, // whether to highlight partial query matches within result page content
      scrollIntoViewBehavior: 'smooth', // the behavior of the scroll text into view, 'smooth' (the page smoothly scrolls to the text - over a few seconds) or 'auto' (the page instantly jumps to the text)
      highlightColor: '#b5f948' // the background color of highlighted text
   },
   contentGroups: {
      include: undefined, // JSON array of content group names to be included in the search result
      exclude: undefined, // JSON array of content group names to be excluded from the search result
      otherName: '', // the name of the uncategorized results that don't belong to any content group
      ignoreOther: false // whether or not to ignore the "other" content group
   },
   tracking: {
      providers: [], // how to track, supported values: 'GA' (Google Analytics), 'GTM' (Google Tag Manager)
      searchCallback: undefined // callback before SERP is reported, SERP events aren't reported if this returns false, you'll get the query as the parameter for the callback
   },
   callbacks: {
      suggestChange: undefined, // callback triggered after suggestion set is changed, takes boolean indicating whether suggestions are visible as argument
      redirect: undefined, // callback to handle search redirects, takes redirect URL as parameter, window.location.href is changed by default
      preSearch: undefined, // a callback that is triggered before the search is executed, e.g. to catch empty queries
      postSearch: undefined, // a callback that is triggered after the search results have been populated
      preSuggest: undefined, // a callback that is triggered before the search suggest is executed, takes the query and search box reference as arguments
      searchResult: undefined, // a callback that is triggered after the search is executed, e.g. to build your own result page from the response
      closeLayer: undefined,
      init: undefined, // function to call after initialization is complete
      moreResults: undefined, // a callback to call when the 'Show More Results' button is clicked
      resultImageError: undefined, // a callback to call for 404 images, should return false value (if the image should be hidden) or a new placeholder image URL, the result of this function has higher priority than the `results.hideResultsWithoutImage` handler, receives the result's DOM Node as first argument
      suggestLine: undefined, // a callback called after a suggestion entry is created
      navigationClick: undefined, // a callback called after a navigation item is clicked, receives the toggled content group name as argument
      preRender: undefined, // a callback called before the search results are rendered (does not get called on 'Show More Results' button click), receives the (grouped) search results as argument, should return a modified search results object if the search results should be modified (e.g. to reorder the content groups), if the received search result object is directly modified, all of the changes are reflected in the search results
      filterRendered: undefined // a callback called after the filter options have been rendered
   },
   accessibility: {
      isMainContent: false, // whether to mark ss360 layer as main content of the page
      resultTopHeadingLevel: 2, // heading level to start with in search result (default h2)
      suggestHeadingLevel: 2, // heading level to use in search suggestions, for content group heading
      searchFieldLabel: 'Search query', // invisible label to be used with screen readers when search field is focused, only be used if value is not empty and there is no label element associated to the search field, default: 'Search input'
      srSuggestionsHiddenText: 'Search suggestions are hidden', // text to announce @screen reader after search suggestions have been hidden
      srNoSuggestionsText: 'No search suggestions', // text to announce @screen reader if no suggestions are available
      srSuggestionsCountText: '#COUNT# search suggestions shown', // text to announce @screen reader after search suggestions have been shown, #COUNT# is replaced with the suggestion count
      srOneSuggestionText: 'One search suggestion shown', // text to announce @screen reader after search suggestions have been shown
      srSuggestBoxControlDescription: 'Use up and down arrows to select available result. Press enter to go to selected search result. Touch device users can use touch and swipe gestures.' // text to announce @screen reader after search input is focused - describes keyboard controls
   },
   specialMobileSuggest: {
      enabled: false, // whether to show special mobile suggests, default: false
      breakpoint: 768, // CSS breakpoint to show mobile suggests (max-width: breakpoint)
      placeholder: '', // placeholder for empty suggestions
      searchBoxPlaceholder: '', // the special search box placeholder
      customTopHtml: '', // additional HTML/text content to be shown above special mobile search field
      animateTransitions: true, // whether to animate special mobile transitions
      resizeSearchBoxOnScroll: true, // whether to resize search field when user scrolls special mobile suggests
      trigger: '.ss360-special-mobile-trigger'
   },
   smart404: {
      identifier: 'Page not found', // the string in the title that identifies the page as a 404 page
      cssIdentifier: undefined, // a CSS selector to an element identifying a 404 page, if the element is present on the page, the page is considered a 404, this setting overrides the 'identifier' setting if set
      resultSelector: '#ss360-404', // a CSS selector that points to a content block where alternative search results should be shown
      caption: 'Try going here instead:' // caption for 404 results
   },
   layout: {
      mobile: { // below 992px
         type: 'list', // can be "grid", "masonry" or "list", default: "list"
         showImages: true, // whether to show images in search result, default: true
         showSnippet: true, // whether to show text snippet in search result, default: true
         showTitle: true, // whether to show title in search result, default: true
         showDataPoints: true, // whether to show data points in search result, default: true
         showUrl: false, // whether to show link in search result, default: false
         gridColsMd: 2, // grid layout column count for devices between 768px and 991px, default: 2
         gridColsSm: 1 // grid layout column count for devices below 768px, default: 1
      },
      desktop: { // 992 px and larger
         type: 'list', //  can be "grid", "masonry" or "list", default: "list"
         showImages: true, // whether to show images in search result, default: true
         showSnippet: true, // whether to show text snippet in search result, default: true
         showTitle: true, // whether to show title in search result, default: true
         showDataPoints: true, // whether to show data points in search result, default: true
         showUrl: false, // whether to show link in search result, default: false
         gridColsXl: 4, // grid layout column count for devices larger than 1200px, default: 4
         gridColsLg: 3 // grid layout column count for devices between 992px and 1199px, default: 3
      },
      masonryCols: { // how many masonry grid columns to show, minimum width to column count mapping (default: 2 columns below 768px, 3 columns between 768px and 991px, 5 columns between 992px and 1199px and 6 columns above 1200px)
         0: 2,
         768: 3,
         992: 5,
         1200: 6
      },
      singleLineGridTitle: false, // whether to force a single line of the search result title with the 'grid' layout
      navigation: {
         position: 'top', // content groups to be shown on 'top', 'left', or 'none'
         type: 'tabs', // can be 'scroll' or 'tabs', for more then 6 (position: 'top') or 10 (position: 'left') content groups 'scroll' navigation is used
         tabSpacingPx: 8, // spacing between tabs
         borderRadiusPx: 3, // tab border radius
         tabTitle: '#NAME# (#COUNT#)', // e.g. 'Recipes (43)'
         showGroupResultCount: true, // set to false to hide the result count for the content groups
         forceTabs: true, // whether to always show tabs (even if too many content groups or a single group are retrieved), applied to desktop only
         fallbackToScroll: false, // whether to use scroll navigation instead of tabs on desktop devices (992px and more) when more than 5 (position: 'top') or 10 (position: 'left') content groups are shown
         showAllResultsTab: true, // set to false to hide the 'All Results' tab
         allResultsTabName: 'All Results', // the name of the 'All Results' tab
         allResultsTabTitle: 'All Results (#COUNT#)' // the title of the all results group, e.g. 'All results (367)'
      }
   },
   voiceSearch: {
      enabled: false, // whether to enable voice search for browsers that support Speech Recognition API (a microphone icon is added to your search field)
      lang: 'en-US', // input language (BCP 47 language tag)
      repositionTrigger: undefined, // a CSS selector to an element which triggers a repositioning of the voice search icon once clicked
      color: '#333333', // mic icon color
      autoPosition: true // whether to inline the position attributes to the voice search icon
   },
   filters: {
      enabled: false, // whether to generate and show filter options, default: false
      position: 'left', // where to place the filter view, can be 'top' (above the search results) or 'left' (to the left of the results) + 'Show filter' button is added for mobile devices; default: 'left' for embedded or fullscreen layouts, otherwise - 'top'
      label: 'Filter', // label of the filter column, also used as screen reader text
      showCounts: true, // whether to show result counts for multiple choice filters
      showQuickDelete: true, // whether to show a 'Quick Delete' bar summarizing active filter options and providing a 'Reset All' button
      deleteAllLabel: 'Reset All', // the label of the button that clears all selected filters
      settings: {}, // range filter settings, e.g. {Price: {unit: '$', step: 1, drawHistogram: false}}
      forceSlideIn: false, // whether to hide filters by default and only show them once toggled
      toggleButtonLabel: 'Filter results', // the label of the filter toggle button shown on mobile
      expandedGroupsCount: 6, // number of filter groups to expand by default, other groups are collapsed (default: 6), set to -1 to expand all filter groups
      multiSelectSearchLabel: 'Search #FILTER_NAME#', // the label of multi-select search input
      multiSelectEmptyState: 'No matching filter options.', // the message to show if the filter option search yields empty results
      multiSelectShowMoreLabel: 'See #COUNT# more',
      multiSelectShowLessLabel: 'See fewer options',
      multiSelectSearchThreshold: 12, // min. number of multi-select options required for the search input to be shown
      multiSelectShowMoreThreshold: 12, // min. number of multi-select options required for the 'See more options' to be shown
      clearGroupLabel: 'clear', // label of the clear all options button within a filter group
      sliderMinUnitLabel: 'Min #UNIT#', // label of the min. val range slider input
      sliderMaxUnitLabel: 'Max #UNIT#', // label of the min. val range slider input
      submitButtonLabel: 'Set' // label of the submit button for range filters
   },
   dataPoints: {
      exclude: [], // data points to be hidden from the UI, array of data point names; you can also uncheck 'Show' in the data point section of the control panel
      single: [], // data points where only the first value should be shown (if multiple values are available), array of data point names; you can also check 'Single' in the data point section of the control panel
      direction: 'row', // the direction of the data point key-value pairs - whether the data points should be shown as a row or as a column (table)
      showNames: true, // whether to show data point names
      collapseBy: ', ' // the (HTML) string to be used when merging rows of the structured data table having the same key, default: ', ', e.g. '', set to null to show data points with the same key in multiple rows
   },
   subConfigs: { // a map of sub config ids to sub configs, the sub config overrides ss360Config settings by providing the full setting path following the dot notation, can be used for localization, e.g. 'de: {"searchBox.placeholder": "Suchen…"}', set the activeSubConfigId to turn on the desired subconfig (this can also be done after the plugin initializes by calling SS360.changeConfig('activeSubConfigId', 'ID');), set the subconfig id to undefined to use the default ss360Config configuration
   },
   activeSubConfigId: undefined
};
</script>
<script src="https://cdn.sitesearch360.com/v13/sitesearch360-v13.min.js" async></script>