Settings
Below is a complete list of the properties allowed on the settings object passed to the sxpr()
function.
Property | Description | Type |
---|---|---|
Basic SettingsThese 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. |
|
Search LinksThese 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 This template must contain a Example: |
|
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 See Search Links page for details. |
|
disableSearchUrlTemplateAutoTags | By 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. |
|
Search ResultsThese 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 | Search input with Alternatively, set a |
|
results | Array of the current search results, in the form of objects with a Alternatively, add a |
|
links | Iterable containing search result link elements, or a selector string for obtaining them. (This is an alternative to |
|
HTML ContainersThese 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 |
|
mediaThumbBarContainer | HTML container for media thumbnail bar widget, or a selector string for obtaining it. Alternatively, set a |
|
instantAnswersContainer | HTML container for instant answers widget, or a selector string for obtaining it. Alternatively, set a |
|
topBarContainer | HTML container for top bar, or a selector string for obtaining it. Alternatively, set a |
|
shoppingContainer | HTML container for shopping results, or a selector string for obtaining it. Alternatively, set a |
|
LocalizationThese 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 Search Expander will attempt to derive |
|
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. |
|
userLocation | An object containing data about the end user's geographical location, specified as This data is used by the Instant Answers widgets, e.g. the weather widget. Each of the object's properties is optional.
|
|
source | A broad category of user agent for analytics purposes. One of:
|
|
Widget appearance and behaviourThese settings control the appearance and behaviour of widgets. | ||
styles | Style settings for customising the appearance of widgets. Example: See Styling page for the available style settings. |
|
wikipediaSnippetPopups | Enables Wikipedia snippet popups in knowledge panel and Instant Answers widgets. (Default false .) |
|
externalLinksOpenInNewTab | Whether to open external links open in a new tab. (Default false .) |
|
allowAudio | Enables audio. (Default false .) |
|
allowDictAudio | Enables dictionary Instant Answers widget audio. (Defaults to allowAudio setting.) |
|
allowSpotifyAudio | Enables Spotify audio. (Defaults to allowAudio setting.) |
|
allowWikipediaAudio | Enables Wikipedia audio. (Defaults to allowAudio setting.) |
|
showLoadingState | Whether to show loading bars in widgets while they load. Set to Individual widget containers can be enabled, disabled or set to Specific types of widget can be targeted individually using objects nested inside some containers, e.g. Most widgets default to |
|
sxAttribution | Whether to show Search Expander attribution at the bottom of widgets. (Default true .) |
|
Layout BreakpointsThese settings are for modifying widget appearance based on viewport size. | ||
screenBreakpoint | The minimum viewport width (px) at which various desktop-oriented layout and behaviour rules apply. |
|
knowledgePanelBreakpoint | The minimum viewport width (px) at which desktop-oriented styles are active for the knowledge panel. |
|
mediaThumbBarBreakpoint | The minimum viewport width (px) at which desktop-oriented styles are active for the media thumbnail bar. |
|
instantAnswersBreakpoints | The minimum viewport width (px) at which desktop-oriented styles are active for the various instant answers widgets. Allowed properties: Example: |
|
shoppingBreakpoint | The minimum viewport width (px) at which desktop-oriented styles are active for the shopping widget. |
|
Knowledge PanelThese settings control the appearance and behaviour of the Knowledge Panel widget. | ||
knowledgePanelTabs | Array of knowledge panel tab IDs to enable. Tab IDs:
(Default all tabs enabled.) |
|
narrowCarouselsBreakOut | If 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 .) |
|
replaceWikipediaLinksWithSearch | If true, Wikipedia links within the knowledge panel will be replaced with internal search links. (Default true .) |
|
googleMapEmbed | Enables the Google Maps embed in the knowledge panel. (Default false .) |
|
knowledgePanelAutoScroll | When 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' .) |
|
knowledgePanelImagePopup | When enabled, clicking on the knowledge panel's main image will bring up a lightbox-style popup. (Default true .) |
|
knowledgePanelCollapse | When 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.) |
|
Tripadvisor PanelThese settings control the appearance and behaviour of the Tripadvisor Panel and Tripadvisor Places Instant Answers widgets. | ||
tripadvisorCollapse | When 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.) |
|
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 (Default |
|
tripadvisorPropertiesMap | Overrides |
|
tripadvisorPlacesMap | Overrides |
|
tripadvisorMapLink | Set the static map to link to a map page for the property. This can be a link to Tripadvisor, Google Maps, a custom map page, or Note that if |
|
tripadvisorMapLinkUrlTemplate | Template for static map image custom link URLs in Tripadvisor panels and Tripadvisor Places Instant Answers widgets. This template must contain a Example: |
|
tripadvisorMapZoomDrag | Whether the map embed should have zoom/drag capability. Requires (Default |
|
tripadvisorMapLayersMenu | Whether the map embed should have a menu for satellite/traffic layers. Requires This setting is incompatible with the (Default |
|
tripadvisorNumReviews | Maximum number of Tripadvisor reviews to display for a property, between 0 and 5 . (Default 3 .) |
|
tripadvisorNumQAs | Maximum number of Tripadvisor Q&A items to display for a property, between 0 and 5 . (Default 3 .) |
|
tripadvisorPartnerId | Input 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. |
|
tripadvisorPlacesExpand | If 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 . |
|
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:
The function should return |
|
handleTripadvisorMapExpand | This function will be called whenever a Tripadvisor Places widget expands to include more locations on the map and property list (see |
|
displayWikipediaBelowTripadvisor | If 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 .) |
|
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. |
|
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.
Example:
|
|
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 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 The |
|
mapLocationPrivacyUrl | Privacy policy page URL for the map location widget. |
|
Instant AnswersThese settings control the appearance and behaviour of the Instant Answers widgets. | ||
tempUnit | Default temperature unit used by the Instant Answers Weather widget: either Celsius ('c' ) or Fahrenheit ('f' ). (Default 'c' .) |
|
dateFormat | Date format used by Instant Answers widgets: either day-month-year ('dmy' ) or month-day-year ('mdy' ). (Default 'dmy' .) |
|
timeFormat | Time format used by Instant Answers widgets: either 24-hour ('24' ) or 12-hour ('12' ). (Default '24' .) |
|
weatherCollapse | If true , the weather widget will be collapsed by default. This will reduce its height until the user clicks the expand button. (Default false .) |
|
smartAnswersImage | Determines 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 .) |
|
Enable/disable widgetsThese settings are used to enable/disable widgets. All widgets are enabled by default so you only need these settings to switch them off. | ||
enableKnowledgePanel | Enables knowledge panel. (Default true .) |
|
enableMediaThumbBar | Enables media thumbnail bar. (Default true .) |
|
enableSearchSuggestions | Enables search suggestions bar. (Default true .) |
|
enableTripadvisorProperties | Enables Tripadvisor property panels. Array of hotel , restaurant , and/or attraction . Alternatively, use true to enable all or false to disable all. (Default true .) |
|
enableTripadvisorPlaces | Enables Tripadvisor Places widgets. Array of hotel , restaurant , and/or attraction . Alternatively, use true to enable all or false to disable all. (Default true .) |
|
enableTripadvisorPlacesForLocations | Enables 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 .) |
|
instantAnswers | Array of instant answers widgets to enable (or true for all): calc , dict , moviesAndTV , smartAnswers , timezone , weather , youtube . |
|
enableWebProducts | This setting enables product ads in either the top bar as a carousel or in the knowledge panel. Set to |
|
shoppingOnly | If This setting overrides the above settings for enabling widgets. |
|
Content RestrictionThese settings allow for restricting certain types of content from users. | ||
safeSearch | Whether to filter out adult content from widgets. (Default true .) |
|
YouTube extrasThese settings enable YouTube-related features. | ||
youTubeEmbed | Enables the YouTube video embed in the Instant Answers widget. (Default false .) |
|
youTubeResultThumbs | Enables the YouTube search result thumbnails, which are added to elements with the data-sxpr-result-thumb attribute. (Default false .) |
|
youTubeCSEThumbs | For Google Custom Search Engine users only. Adds YouTube search result thumbnails into Google CSE result containers. Overrides youTubeResultThumbs . (Default false .) |
|
Request ProxyingThese 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: Example: See the documentation for more details. |
|
assetsUrlTemplate | URL template for proxying requests for Search Expander assets such as CSS and JavaScript files. Example: Example: Example: |
|
imageUrlTemplate | URL template for proxying image requests made by Search Expander widgets. Example: |
|
audioUrlTemplate | URL template for proxying requests for third-party audio in Search Expander widgets. Example: |
|
wikipediaApiUrlTemplate | URL template for proxying requests to the Wikipedia API in Search Expander widgets (for snippet popups). Example: |
|
imageUrlNoProxy | If Example: |
|
audioUrlNoProxy | If Example: |
|
Supplemental API Request DataThese 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 |
|
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 |
|
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 |
|
ShoppingThese 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 It is strongly recommended that you provide this setting, unless you are using a Example: |
|
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 |
|
shoppingAutoScroll | Whether to automatically scroll the viewport to the top of the shopping widget after product thumbnails have been loaded. Default |
|
enableSponsoredProducts | Whether to add a carousel of sponsored product thumbs across the top of the shopping widget. (Default |
|
enableEcoProducts | Whether to add a carousel of eco-friendly product thumbs across the top of the shopping widget. (Default |
|
webProductsPriority | Whether to prioritise Kelkoo product ads or Yadore product ads where they appear on your web SERP. (Default |
|
webProductsAllowAdult | Whether to allow adult product ads in the web SERP shopping widgets. (Default Note that if |
|
lazyLoadWebProducts | Whether to enable image lazy-loading on product ads. (Default true .) |
|
shoppingAllowAdult | Whether to allow adult product ads in the shopping widget. (Default Note that if |
|
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 Note that a valid URL template must be provided for the |
|
Client-side storageThese settings control the use of client-side storage. | ||
allowLocalStorage | Set to To opt in to specific uses of
Default |
|
API Host SelectionThese settings relate to the selection of Search Expander API host. | ||
apiHost | Search 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' . |
|
DevelopmentThese settings are relevant to development and troubleshooting. | ||
logLevel | Controls 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). |
|