Settings

Below is a complete list of the properties allowed on the settings object passed to the sxpr() function.

PropertyDescriptionType

Basic Settings

These settings are required for basic functionality.
se

Search engine ID (required).

This ID can be found at account/settings after you have created a search engine for your account.

string

Search Links

These settings are used to control the behaviour of internal search links in widgets.
searchUrlTemplate

Template for widget search link URLs.

It is strongly recommended to provide this, unless you are setting a handleSearchClick function instead.

This template must contain a {searchTerms} tag, and may contain {mediaThumbBar}, {searchSuggestions}, and {wordToDefine} tags.

Example: /?q={searchTerms}

string
handleSearchClick

Click handler for the internal search links in widgets.

Used where new search results are loaded dynamically (using JavaScript) rather than via traditional page navigation, meaning that searchUrlTemplate alone is insufficient. If set, search links will not be followed and this function will handle the click instead.

See Search Links page for details.

(data: {
  q: string;
  mediaThumbBar?: string;
  searchSuggestions?: string;
  wordToDefine?: string;
  link: HTMLAnchorElement;
  event: MouseEvent;
  url: string | undefined;
}) => void
disableSearchUrlTemplateAutoTagsBy default, Search Expander will add missing mediaThumbBar, searchSuggestions, and wordToDefine tags into the search URL template, as part of a URL query string. Set this to false to disable this behaviour.
boolean

Search Results

These settings are used to let Search Expander know about your search page's results and search query.
q

The current search query.

If unset, Search Expander will attempt to get the value from a search input (see searchInput) or the current URL.

string
searchInput

Search input with q value.

Alternatively, set a data-sxpr-input HTML attribute on the input (or add q setting).

HTMLInputElement | string
results

Array of the current search results, in the form of objects with a url and title property.

Alternatively, add a data-sxpr-link attribute to each of your search result links, or set a links property.

{
  url: string;
  title?: string;
}[]

HTML Containers

These settings are used to tell Search Expander where to render its widgets. They are an alternative to adding data-sxpr-… attributes to your markup.
knowledgePanelContainer

HTML container for knowledge panel widget, or a selector string for obtaining it.

Alternatively, set a data-sxpr-knowledge-panel HTML attribute on the container.

HTMLElement | string
mediaThumbBarContainer

HTML container for media thumbnail bar widget, or a selector string for obtaining it.

Alternatively, set a data-sxpr-media-thumb-bar HTML attribute on the container.

HTMLElement | string
instantAnswersContainer

HTML container for instant answers widget, or a selector string for obtaining it.

Alternatively, set a data-sxpr-instant-answers HTML attribute on the container.

HTMLElement | string
topBarContainer

HTML container for top bar, or a selector string for obtaining it.

Alternatively, set a data-sxpr-top-bar HTML attribute on the container.

HTMLElement | string
shoppingContainer

HTML container for shopping results, or a selector string for obtaining it.

Alternatively, set a data-sxpr-shopping HTML attribute on the container.

HTMLElement | string

Localization

These settings relate to support for different languages and locations.
lang

Two-letter ISO 639-1 language code, used to get results in a particular language.

Currently supported languages are en, de, es, fr, it, nl.

Search Expander will attempt to derive lang from browser settings unless this value is explicitly set.

'en' | 'de' | 'es' | 'fr' |
'it' | 'nl'
market

Two-letter country code, used to specify the end user market.

This setting is normally detected automatically from browser settings, but can be specified explicitly if desired.

'ae' | 'at' | 'au' | 'be' |
'br' | 'ca' | 'ch' | 'cz' |
'de' | 'dk' | 'es' | 'fi' |
'fr' | 'gr' | 'hk' | 'hu' |
'id' | 'ie' | 'in' | 'it' |
'jp' | 'kr' | 'mx' | 'my' |
'nb' | 'nl' | 'no' | 'nz' |
'ph' | 'pl' | 'pt' | 'ro' |
'ru' | 'se' | 'sg' | 'sk' |
'tr' | 'uk' | 'us' | 'vn' |
'za'
userLocation

An object containing data about the end user's geographical location, specified as city, state, country, lat (latitude) and lng (longitude).

This data is used by the Instant Answers widgets, e.g. the weather widget. Each of the object's properties is optional.

lat and lng must be specified as numbers (decimal degrees).

{
  city?: string;
  state?: string;
  country?: string;
  lat?: number;
  lng?: number;
}
source

A broad category of user agent for analytics purposes. One of:

  • 'desktop'
  • 'tablet'
  • 'phone'
  • 'ios_app_phone'
  • 'ios_app_tablet'
  • 'android_app_phone'
  • 'android_app_tablet'
  • 'firefox_extension'
  • 'chrome_extension'
  • 'edge_extension'
string

Widget appearance and behaviour

These settings control the appearance and behaviour of widgets.
styles

Style settings for customising the appearance of widgets.

Example: { foreground: '#222' }

See Styling page for the available style settings.

object
wikipediaSnippetPopupsEnables Wikipedia snippet popups in knowledge panel and Instant Answers widgets. (Default false.)
boolean
externalLinksOpenInNewTabWhether to open external links open in a new tab. (Default false.)
boolean
allowAudioEnables audio. (Default false.)
boolean
allowDictAudioEnables dictionary Instant Answers widget audio. (Defaults to allowAudio setting.)
boolean
allowSpotifyAudioEnables Spotify audio. (Defaults to allowAudio setting.)
boolean
allowWikipediaAudioEnables Wikipedia audio. (Defaults to allowAudio setting.)
boolean
showLoadingState

Whether to show loading bars in widgets while they load. Set to true to enable all, false to disable all, and 'blank' to take up visual space during loading without showing loading bars.

Individual widget containers can be enabled, disabled or set to 'blank', e.g. {knowledgePanel: false, instantAnswers: 'blank'}.

Specific types of widget can be targeted individually using objects nested inside some containers, e.g. {instantAnswers: {calc: false, dict: 'blank'}, topBar: {searchSuggestions: true}}.

Most widgets default to true.

boolean | 'blank' | {
  instantAnswers?: boolean | 'blank' | {
    calc: boolean | 'blank';
    dict: boolean | 'blank';
    moviesAndTV: boolean | 'blank';
    smartAnswers: boolean | 'blank';
    timezone: boolean | 'blank';
    tripadvisor: boolean | 'blank';
    youtube: boolean | 'blank';
    weather: boolean | 'blank';
  };
  knowledgePanel?: boolean | 'blank' | {
    productAds: boolean | 'blank';
    tripadvisor: boolean | 'blank';
    wikipedia: boolean | 'blank';
  };
  mediaThumbBar?: boolean | 'blank';
  topBar?: boolean | 'blank' | {
    productAds: boolean | 'blank';
    searchSuggestions: boolean | 'blank';
  };
}
sxAttributionWhether to show Search Expander attribution at the bottom of widgets. (Default true.)
boolean

Layout Breakpoints

These settings are for modifying widget appearance based on viewport size.
screenBreakpointThe minimum viewport width (px) at which various desktop-oriented layout and behaviour rules apply.
number
knowledgePanelBreakpointThe minimum viewport width (px) at which desktop-oriented styles are active for the knowledge panel.
number
mediaThumbBarBreakpointThe minimum viewport width (px) at which desktop-oriented styles are active for the media thumbnail bar.
number
instantAnswersBreakpoints

The minimum viewport width (px) at which desktop-oriented styles are active for the various instant answers widgets. Allowed properties: calc, dict, moviesAndTV, smartAnswers, timezone, weather, youtube.

Example: { calc: 768, weather: 1024 }

{ [name: string]: number }
shoppingBreakpoint

The minimum viewport width (px) at which desktop-oriented styles are active for the shopping widget.

number

Knowledge Panel

These settings control the appearance and behaviour of the Knowledge Panel widget.
knowledgePanelTabs

Array of knowledge panel tab IDs to enable.

Tab IDs:

  • overview
  • summary
  • actorCredits
  • albums
  • albumTracks
  • artistSimilar
  • authorBooks
  • bookAuthorBooks
  • bookSimilar
  • cast
  • movieTvSimilar
  • trailers
  • tvEpisodes
  • songs
  • streaming
  • videoGameFranchiseGames
  • videoGameSimilar
  • videoGameVideos

(Default all tabs enabled.)

string[]
narrowCarouselsBreakOutIf true, on narrow viewports, the knowledge panel thumbnail carousels will stretch horizontally to cover the viewport width, breaking out of the knowledge panel container to give a more seamless appearance. (Default true.)
boolean
replaceWikipediaLinksWithSearchIf true, Wikipedia links within the knowledge panel will be replaced with internal search links. (Default true.)
boolean
googleMapEmbedEnables the Google Maps embed in the knowledge panel. (Default false.)
boolean
knowledgePanelAutoScrollWhen enabled, the browser window will automatically scroll to the knowledge panel content when one of its tabs is selected. By default, this feature is enabled on small screens only. (Default 'small'.)
'small' | 'large' |
'always' | 'never'
knowledgePanelImagePopupWhen enabled, clicking on the knowledge panel's main image will bring up a lightbox-style popup. (Default true.)
boolean
knowledgePanelCollapseWhen set to short, some knowledge panel content will be collapsed on mobile viewports, in order to reduce its height. (Default tall, i.e. no collapsing.)
'short' | 'tall'

Tripadvisor Panel

These settings control the appearance and behaviour of the Tripadvisor Panel and Tripadvisor Places Instant Answers widgets.
tripadvisorCollapseWhen set to short, some Tripadvisor panel content will be collapsed on mobile viewports, in order to reduce its height. (Default tall, i.e. no collapsing.)
'short' | 'tall'
tripadvisorMap

Choose between a Here Maps embed, a Google Maps embed, or no map, for Tripadvisor Knowledge Panels and Tripadvisor Places Instant Answers.

Note that, when using heremaps, a hereMapsApiKey must be provided. For Tripadvisor Knowledge Panels, Here Maps static images will be served using your hereMapsApiKey. For Tripadvisor Places Instant Answers, Here Maps vector tiles will be served using your hereMapsApiKey.

(Default heremaps.)

'heremaps' | 'google' | 'none'
tripadvisorPropertiesMap

Overrides tripadvisorMap setting for Tripadvisor Properties knowledge panels.

'heremaps' | 'google' | 'none'
tripadvisorPlacesMap

Overrides tripadvisorMap setting for Tripadvisor Places Instant Answers widgets.

'heremaps' | 'google' | 'none'
tripadvisorMapLinkUrlTemplate

Template for static map image custom link URLs in Tripadvisor panels and Tripadvisor Places Instant Answers widgets.

This template must contain a {searchTerms} tag, which will be populated with a search query.

Example: /?q={searchTerms}

string
tripadvisorMapZoomDrag

Whether the map embed should have zoom/drag capability.

Requires tripadvisorMap, tripadvisorPropertiesMap or tripadvisorPlacesMap to be set to 'heremaps' and hereMapsApiKey to be set to a valid API key.

(Default false.)

boolean
tripadvisorMapLayersMenu

Whether the map embed should have a menu for satellite/traffic layers.

Requires tripadvisorMap, tripadvisorPropertiesMap or tripadvisorPlacesMap to be set to 'heremaps' and hereMapsApiKey to be set to a valid API key.

This setting is incompatible with the hereMapsProxy setting.

(Default false.)

boolean
tripadvisorNumReviewsMaximum number of Tripadvisor reviews to display for a property, between 0 and 5. (Default 3.)
number
tripadvisorNumQAsMaximum number of Tripadvisor Q&A items to display for a property, between 0 and 5. (Default 3.)
number
tripadvisorPartnerIdInput your Tripadvisor partner ID here, e.g. '12345'. This will then be appended to all our Tripadvisor links. If you leave this blank, we will use our own Tripadvisor partner ID and attempt to allocate any Tripadvisor revenue we accrue from clicks on hotel links to your account based on the number of clicks your users make on our Tripadvisor hotel-related links. In this case, these links will be redirected via SearchExpander.com.
string
tripadvisorPlacesExpandIf true, the Tripadvisor Places widget will have an option to expand from 3 to up to 8 properties. If a user clicks or taps on the icon to expand the list, this will trigger an additional request for billing purposes. Default true.
boolean
handleTripadvisorMap

This function will be called whenever a Tripadvisor Places map is ready to load. If set, any default map settings are ignored and this function is expected to handle custom map rendering. It is passed an object containing the following data:

container: HTMLElement;
properties: {
	lat: number | null;
	lng: number | null;
	name: string;
	id: number;
	visible: boolean;
}[]

container is the HTML element in which the map is normally rendered. properties is an array of objects specifying each location.

The function should return false if there was an error and the map could not be rendered.

(data) => undefined | false | Promise<undefined | false>
handleTripadvisorMapExpand

This function will be called whenever a Tripadvisor Places widget expands to include more locations on the map and property list (see tripadvisorPlacesExpand). It is passed the same argument as handleTripadvisorMap.

(data) => void
displayWikipediaBelowTripadvisorIf true, where there is both a Tripadvisor panel and a Wikipedia-based knowledge panel available, the Wikipedia panel will be displayed below the Tripadvisor panel in a collapsed format. If false, only the Tripadvisor panel will be displayed. (Default true.)
boolean
hereMapsApiKey

Your own Here Maps API key. If not set, Here Maps map embeds and images will be disabled.

Our Tripadvisor Places Instant Answers widget uses Here Maps vector map tiles, while our Tripadvisor Knowledge Panel uses Here Maps static map images. The API key you specify here will be used to retrieve both.

string
hereMapsProxy

This object can be used to configure proxy settings for Here Maps, if they are used in the Tripadvisor Places IA widget. To proxy requests to Here Maps, you must specify two domains, optionally adding paths, subdomains and protocols.

js.domain must be a domain (with optional path) for a proxy forwarding requests to https://js.api.here.com.

vector.domain must be a domain (with optional path) for a proxy forwarding requests to https://vector.hereapi.com.

Example:

{
    js: {
        domain: 'example.com/proxy/js',
        protocol: 'https',    // optional
        subdomain: null,      // optional
    },
    vector: {
        domain: 'example.com/proxy/vector',
        protocol: 'http',     // optional
        subdomain: 'example', // optional
    }
}

object
mapLocationWidget

Whether to add a prompt for the user to enter their location data for the purposes of Tripadvisor-related queries. The prompt will be part of the Tripadvisor Places IA widget. Default true.

Note: This feature makes use of the Geolocation web API, which will cause the user's browser to ask them for permission to access their location data. The data is stored client-side in localStorage and overrides any user location data set explicitly in the sxpr settings object.

The allowLocalStorage or allowLocalStorage.allowLocationStorage setting must be true to allow the user location widget to appear.

boolean
mapLocationPrivacyUrl

Privacy policy page URL for the map location widget.

string

Instant Answers

These settings control the appearance and behaviour of the Instant Answers widgets.
tempUnitDefault temperature unit used by the Instant Answers Weather widget: either Celsius ('c') or Fahrenheit ('f'). (Default 'c'.)
'c' | 'f'
dateFormatDate format used by Instant Answers widgets: either day-month-year ('dmy') or month-day-year ('mdy'). (Default 'dmy'.)
'dmy' | 'mdy'
timeFormatTime format used by Instant Answers widgets: either 24-hour ('24') or 12-hour ('12'). (Default '24'.)
'24' | '12'
weatherCollapseIf true, the weather widget will be collapsed by default. This will reduce its height until the user clicks the expand button. (Default false.)
boolean
smartAnswersImageDetermines whether an image is added to the Smart Answers widget. Set as small for small viewports, large for large viewports, always to always show an image, and never to never show an image. (Default always.)
'small' | 'large' |
'always' | 'never'

Enable/disable widgets

These settings are used to enable/disable widgets. All widgets are enabled by default so you only need these settings to switch them off.
enableKnowledgePanelEnables knowledge panel. (Default true.)
boolean
enableMediaThumbBarEnables media thumbnail bar. (Default true.)
boolean
enableSearchSuggestionsEnables search suggestions bar. (Default true.)
boolean
enableTripadvisorPropertiesEnables Tripadvisor property panels. Array of hotel, restaurant, and/or attraction. Alternatively, use true to enable all or false to disable all. (Default true.)
string[] | boolean
enableTripadvisorPlacesEnables Tripadvisor Places widgets. Array of hotel, restaurant, and/or attraction. Alternatively, use true to enable all or false to disable all. (Default true.)
string[] | boolean
enableTripadvisorPlacesForLocationsEnables Tripadvisor Places For Locations widgets. Array of hotel, restaurant, and/or attraction. Alternatively, use true to enable all or false to disable all. (Default true.)
string[] | boolean
instantAnswersArray of instant answers widgets to enable (or true for all): calc, dict, moviesAndTV, smartAnswers, timezone, weather, youtube.
string[] | true
enableWebProducts

This setting enables product ads in either the top bar as a carousel or in the knowledge panel.

Set to true or 'topBar' to enable product ads in a top bar carousel, or to 'knowledgePanel' to enable product ads in a section of the knowledge panel, or false to disable. (Default false.)

boolean | 'topBar' |
'knowledgePanel'
shoppingOnly

If true, all widgets apart from shopping widgets will be disabled and requests will not be billable. Default false.

This setting overrides the above settings for enabling widgets.

boolean

Content Restriction

These settings allow for restricting certain types of content from users.
safeSearchWhether to filter out adult content from widgets. (Default true.)
boolean

YouTube extras

These settings enable YouTube-related features.
youTubeEmbedEnables the YouTube video embed in the Instant Answers widget. (Default false.)
boolean
youTubeResultThumbsEnables the YouTube search result thumbnails, which are added to elements with the data-sxpr-result-thumb attribute. (Default false.)
boolean
youTubeCSEThumbsFor Google Custom Search Engine users only. Adds YouTube search result thumbnails into Google CSE result containers. Overrides youTubeResultThumbs. (Default false.)
boolean

Request Proxying

These settings allow you to proxy client-side requests to third-parties made by Search Expander (including Search Expander itself) via servers that you control.
apiUrlTemplate

URL template for proxying requests to the Search Expander API.

Example: /api-proxy?path={path}

Example: https://proxy.example.com{path}

See the documentation for more details.

string
assetsUrlTemplate

URL template for proxying requests for Search Expander assets such as CSS and JavaScript files.

Example: /assets-proxy?path={path}

Example: /assets-proxy?url={url}

Example: https://proxy.example.com{path}

string
imageUrlTemplate

URL template for proxying image requests made by Search Expander widgets.

Example: /proxy?url={url}

string
audioUrlTemplate

URL template for proxying requests for third-party audio in Search Expander widgets.

Example: /proxy?url={url}

string
wikipediaApiUrlTemplate

URL template for proxying requests to the Wikipedia API in Search Expander widgets (for snippet popups).

Example: /proxy?url={url}

string
imageUrlNoProxy

If imageUrlTemplate is set, you can exclude certain domains from being filtered by this template by adding them to this setting.

Example: ['wikimedia.org']

string | string[]
audioUrlNoProxy

If audioUrlTemplate is set, you can exclude certain domains from being filtered by this template by adding them to this setting.

Example: ['wikimedia.org']

string | string[]

Supplemental API Request Data

These settings are for requesting particular types of widget content from Search Expander. They will usually be taken care of automatically but in certain contexts it can be useful to provide them manually.
mediaThumbBar

ID used to trigger a relevant media thumbnail bar.

Normally this value will be automatically picked up via URL data, but where this is not possible you can set it manually.

(Alternatively, add the value to a hidden input with the name sx-media-thumb-bar.)

string
searchSuggestions

ID used to trigger a relevant search suggestions bar.

Normally this value will be automatically picked up via URL data, but where this is not possible you can set it manually.

(Alternatively, add the value to a hidden input with the name sx-search-suggestions.)

string
wordToDefine

Word to define using the dictionary instant answers widget.

Normally this value will be picked up via URL data, but where this is not possible you can set it manually.

(Alternatively, add the value to a hidden input with the name sx-word-to-define.)

string

Shopping

These settings relate to serving product ads from a shopping route. If you are not serving product ads, they can be ignored.
shoppingUrlTemplate

Template for shopping route link URLs. These links will appear in widgets and navigate users to your shopping route.

This template should be passed to both sxpr() and sxpr.shopping().

It is strongly recommended that you provide this setting, unless you are using a handleShoppingClick function instead.

Example: /shopping/?q={searchTerms}

string
handleShoppingClick

Click handler for the internal shopping route links in widgets.

Used where new shopping results are loaded dynamically (using JavaScript) rather than via traditional page navigation, meaning that shoppingUrlTemplate alone is insufficient. If set, shopping route links will not be followed and this function will handle the click instead.

More info

(data: {
  q: string;
  origQ: string;
  link: HTMLElement;
  event: MouseEvent;
  url: string | undefined;
}) => void
shoppingAutoScroll

Whether to automatically scroll the viewport to the top of the shopping widget after product thumbnails have been loaded.

Default small (i.e. auto-scrolling behaviour applies to small viewports only).

'small' | 'large' |
'always' | 'never'
enableSponsoredProducts

Whether to add a carousel of sponsored product thumbs across the top of the shopping widget. (Default true.)

boolean
enableEcoProducts

Whether to add a carousel of eco-friendly product thumbs across the top of the shopping widget. (Default false.)

boolean
webProductsPriority

Whether to prioritise Kelkoo product ads or Yadore product ads where they appear on your web SERP. (Default kelkoo.)

'kelkoo' | 'yadore'
webProductsAllowAdult

Whether to allow adult product ads in the web SERP shopping widgets. (Default true.)

Note that if safeSearch is true (the default), this setting is overridden and adult product ads are not allowed on the web SERP.

boolean
lazyLoadWebProductsWhether to enable image lazy-loading on product ads. (Default true.)
boolean
shoppingAllowAdult

Whether to allow adult product ads in the shopping widget. (Default true.)

Note that if safeSearch is true (the default), this setting is overridden and adult product ads are not allowed in the shopping widget.

boolean
enableShoppingBrowserHistory

Whether to add a new browser history entry when the user updates the shopping widget filter parameters. This allows for URL sharing and bookmarking of particular shopping results. (Default true.)

Note that a valid URL template must be provided for the shoppingUrlTemplate setting, e.g. https://example.com/shop/?q={searchTerms}.

boolean

Client-side storage

These settings control the use of client-side storage.
allowLocalStorage

Set to true to allow storage of a small amount of client-side data in localStorage. This can improve user experience, including increasing request speed. This is never used for tracking or personal data collection. No cookies are set or read by Search Expander.

To opt in to specific uses of localStorage, specify an object instead of a boolean and specify a boolean for one or more of:

  • allowSuccessFlagStorage: Used for improved front-end performance
  • allowMarketCodeStorage: User market is used for analytics and product ads (where these are opted into). You can set a market value explicitly to eliminate the need for this.
  • allowLocationStorage: Used where user location is useful for serving relevant data, including Tripadvisor maps and weather data. User location data is approximate.

Default false.

boolean | {
  allowSuccessFlagStorage: boolean;
  allowMarketCodeStorage: boolean;
  allowLocationStorage: boolean;
}

API Host Selection

These settings relate to the selection of Search Expander API host.
apiHostSearch Expander's API is hosted in the EU and the US. If you want to force a choice between these servers, you can do so by setting apiHost to either 'eu', 'eu2' or 'us'.
'eu' | 'eu2' | 'us'

Development

These settings are relevant to development and troubleshooting.
logLevelControls browser log output. If unset, no messages are sent to the browser console. If error, only error messages are sent. If warning, warning messages are also sent. If debug, messages about some normal operations are also sent (this is recommended during development).
'error' | 'warning' | 'debug'

» Back to documentation menu