Advanced JavaScript customisation

Start with the settings in Customise the design. If you need changes that are not available there, override supported storefront configuration through JavaScript.

warning

These options affect the live search experience. Test changes on a duplicate theme before applying them to your production storefront.

Add JavaScript configuration

On page load, settings configured in the app are exposed on the window.HSData object.

Add an Essential script to the page head in BigCommerce Script Manager. The following example changes the storefront search placeholder.

<script>
    window.HSData = window.HSData || {};
    window.HSData.translations = {
       "search_placeholder": "What are you looking for?"
    }
</script>

Customisation example

Translate the search experience

You can modify the text used within the search experience by overriding the window.HSData.translations object.

<script>
    window.HSData = window.HSData || {};
    window.HSData.translations = {
      "apply": "Apply",
      "clear": "Clear",
      "next": "Next",
      "previous": "Previous",
      "per_page": "Per Page",
      "quick_view": "Quick View",
      "was": "Was",
      "now": "Now",
      "and_up": "& up",
      "recent_searches": "Recent searches",
      "sort_by": "Sort by",
      "results_for": "Results for",
      "all_products": "all products",
      "view_all": "View all",
      "no_products_found": "No products found",
      "why_not_try": "why not try",
      "top_searches": "Top searches",
      "show_more": "Show more",
      "show_less": "Show less",
      "search_placeholder": "What are you looking for?"
  }
</script>

Configuration options

The following is a full list of configuration options that can be defined.

info

The app provides these values automatically, and many are available in the app settings. Override only the values you need.

HSData

Field	Type	Notes
app_overlay_id	string	DOM ID of the overlay container.
app_suggestions_id	string	DOM ID for search suggestions.
app_results_id	string	DOM ID for search results.
app_wrapper	string	DOM ID of the main wrapper element.
search_query_param	string	Query string parameter for the search term.
search_option_param	string	Query string parameter for search options.
search_path	string	Path used to trigger search.
hyper_search_cookie	string	Cookie name used for session or tracking.
is_hidden_class	string	CSS class used to hide elements.
catalog_entity	string	Entity name for catalog search.
content_entity	string	Entity name for content search.
horizontal_filter	string	CSS selector for horizontal filters.
vertical_filter	string	CSS selector for vertical filters.
collapsed_filter	string	CSS selector for collapsed filters.
is_searching_class	string	CSS class to show during search loading.
api_domain	string	Base domain used for API requests.
store_hash	string	BigCommerce store hash.
channel_id	string	BigCommerce channel ID.
typesense_config	TypesenseConfig | null	Configuration for Typesense search engine.
search_config	SearchConfig | null	Settings for different search collections.
search_filters	SearchFilters[] | null	Array of available filters.
searchable_fields	SearchableFields[] | null	Fields that can be searched.
search_sort_orders	SortOrder[] | null	Sorting options for search results.
search_settings	SearchSettings | null	Settings for search display and behavior.
search_product_card	string	CSS selector for the product card.
search_inline_product_card	string	CSS selector for the inline product card.
search_content	string | null	Optional HTML for search content results.
zero_results_content	string | null	Optional HTML for zero results message.
active_currency_code	string	Current store currency.
default_currency_code	string	Default store currency.
currency_fields	string[]	Fields that support multiple currencies.
customer_id	number | null	ID of the logged-in customer.
customer_group_id	number | null	Group ID of the logged-in customer.
default_sort_by	string	Default sorting field.
default_desktop_filter	string	Default filter view for desktop.
default_mobile_filter	string	Default filter view for mobile.
sort_order_count	string	Used to configure sort order display.
facet_type_group	string	Defines groupings for facets.
translations	Translations (optional)	Custom text translations for UI.
showOverlay	() => void (optional)	Function to show the overlay.
hideOverlay	() => void (optional)	Function to hide the overlay.
default_image_url	string (optional)	Fallback image URL for products.

SearchableFields

Field	Type	Notes
field	string	Field that is searchable.
priority	number	Priority of this field when ranking results.

SearchCollection

Field	Type	Notes
collection	string	Name of the Typesense collection.
entity	string	Entity type being searched.
params	TypesenseParams	Search parameters.

SearchConfig

Field	Type	Notes
catalog	SearchCollection	Search configuration for product catalog.
content	SearchCollection	Search configuration for content.
top_searches	SearchCollection	Search configuration for top searches.
redirects	SearchCollection	Search configuration for redirects.

SearchFilters

Field	Type	Notes
display_name	string	Label to display for the filter.
field	string	Field to filter on.
facet_type	string	Type of facet (e.g., checkbox, slider).
sort_order	string	Order in which the filter appears.

SearchSettings

Field	Type	Notes
integration_method	'suggestions' | 'overlay'	Integration style.
products_per_row	number	Number of products displayed per row.
desktop_filter	string	Default desktop filter display type.
mobile_filter	string	Default mobile filter display type.
pagination_default_value	number	Default pagination size.
pagination_options	number[]	Available pagination options.
pagination_type	string	Type of pagination UI.
container_width	string	CSS value for container width.
mobile_breakpoint	number	Pixel value for mobile breakpoint.
limit	number	Maximum number of results.
filter_limit	number	Maximum number of filters.
toggle_button_target	string	Selector for filter toggle button.
overlay_position_target	string	Selector for overlay positioning.
category_filter_type	string	Type of category filtering.
secondary_sort_order	string (optional)	Optional secondary sort order.

SortOrder

Field	Type	Notes
display_name	string	Label shown for the sort option.
sort_order	string	Sort logic applied (e.g. 'price:asc').

Translations

Field	Type	Notes
apply	string	Label for apply button.
clear	string	Label for clear/reset button.
next	string	Label for next page.
previous	string	Label for previous page.
per_page	string	Label for per-page selector.
was	string	Prefix for showing previous price.
now	string	Prefix for showing current price.
and_up	string	Label for filters like '4 stars and up'.
recent_searches	string	Heading for recent searches.
results_for	string	Prefix for search result header.
no_products_found	string	Message for zero search results.
why_not_try	string	Follow-up suggestion heading.
top_searches	string	Heading for top searches.
show_more	string	Text for show more toggle.
show_less	string	Text for show less toggle.

TypesenseConfig

Field	Type	Notes
nearest_node	TypesenseNode | null	Preferred Typesense node for faster querying.
nodes	TypesenseNode[]	List of fallback Typesense nodes.
api_key	string	Private API key for Typesense.
product_api_key	string	API key used for product-specific queries.

TypesenseNode

Field	Type	Notes
host	string	Hostname of the Typesense server.
port	string	Port number for the Typesense server.
path	string	Optional path prefix.
protocol	string	Protocol used, typically 'http' or 'https'.

TypesenseParams

Field	Type	Notes
query_by	string	Comma-separated list of fields to query.
per_page	number (optional)	Number of results per page.
highlight_full_fields	string (optional)	Fields to highlight.
filter_by	string (optional)	Filter expression.
group_by	string (optional)	Field to group results by.
sort_by	string (optional)	Field to sort by.