Customize UI Kit Labels

Updated

In this how-to guide, you'll learn how to customize or translate hardcoded text in SearchStax UI Kit components. While most UI elements can be modified through templates, some labels, like the "Relevance" sort option, require a different approach.

By the end of this guide, you'll be able to:

  • Use the afterSearch hook to modify the UI after a search completes
  • Write a JavaScript snippet to find and replace a specific text label
  • Adapt the solution for a multi-language implementation

Prerequisites

Before you start, you'll need:

  • A working SearchStax Site Search implementation that uses a UI Kit (JavaScript, Vue, React, or Angular)
  • Access to modify the front-end JavaScript code for your search page
  • A basic understanding of JavaScript and DOM manipulation

Use the afterSearch Hook to Modify UI Elements

The SearchStax UI Kits provide several hooks that allow you to execute custom code at specific points in the search lifecycle. To modify a UI element that has already been rendered, you can use the afterSearch hook. This hook runs after the search results have been returned and displayed, giving your code access to the rendered DOM.

The following JavaScript snippet shows how to use the afterSearch hook to find the "Relevance" option in the sorting widget and replace it with a different string. 

afterSearch: (results) => {
  setTimeout(() => {
    // Translate 'Relevance' in Sort By options
    const sortSelect = document.getElementById('searchstax-search-order-select');
    if (sortSelect && sortSelect.tagName === 'SELECT') {
      Array.from(sortSelect.options).forEach((option) => {
        if (option.text.trim() === 'Relevance') {
          option.text = '<YOUR_TRANSLATED_STRING>';
        }
      });
    }
  }, 0);
  const copy = [...results];
  return copy;
},

Replace <YOUR_TRANSLATED_STRING> with your own text.

Adapting for Multiple Languages

Hardcoding a single translation isn't ideal for a multi-language site. A more robust solution is to fetch the correct translation dynamically based on the user's selected language.

The following example shows how you might integrate this with a hypothetical translation function. 

afterSearch: (results) => {
  setTimeout(() => {
    const currentLanguage = <YOUR_LANGUAGE_DETECTION_LOGIC>; // e.g., 'es' for Spanish
    const translatedString = <YOUR_TRANSLATION_FUNCTION>('Relevance', currentLanguage); // e.g., 'Relevancia'

    const sortSelect = document.getElementById('searchstax-search-order-select');
    if (sortSelect && sortSelect.tagName === 'SELECT') {
      Array.from(sortSelect.options).forEach((option) => {
        if (option.text.trim() === 'Relevance') {
          option.text = translatedString;
        }
      });
    }
  }, 0);
  const copy = [...results];
  return copy;
},

In this version:

  • <YOUR_LANGUAGE_DETECTION_LOGIC> should be replaced with the code you use to determine the current page language.
  • <YOUR_TRANSLATION_FUNCTION> should be replaced with a call to your site's internationalization library or a lookup from a translation object.

Verify Your Changes

To confirm the solution is working:

  1. Implement the afterSearch hook in your search page's configuration.
  2. Refresh your search page in the browser.
  3. Confirm that the "Sort By" dropdown now displays your custom string instead of "Relevance."

Customize UI Elements on Page Load

The afterSearch hook modifies elements that are part of the search results. To modify elements that appear on the initial page load, like the search input placeholder, you need a different approach. These elements are often rendered dynamically by the UI Kit's script before a search is ever run.

You can't use the afterSearch or beforeSearch hooks to modify them, as the DOM elements might not exist yet when those hooks fire. Instead, you can use a MutationObserver to watch for the element to be added to the page and then change it.

In this tutorial, you'll learn how to modify the search input's placeholder text. You can adapt this method to change other elements that appear on page load.

Use a MutationObserver to Modify the Search Input Placeholder

The following JavaScript snippet shows how to use a MutationObserver within the window.onload event handler. It waits for the #searchstax-search-input element to appear in the DOM and then changes its placeholder text.

You can add this snippet to the template code for your search page. 

function overrideInputPlaceholder() {
  const observer = new MutationObserver((mutationsList, observer) => {
    const input = document.getElementById("searchstax-search-input");
    if (input) {
      // The input element is now in the DOM.
      // You can now modify it.
      input.placeholder = "Translated Search Placeholder...";
      
      // Stop observing once the element is found and modified.
      observer.disconnect();
    }
  });

  // Start observing the document body for changes to child elements.
  observer.observe(document.body, {
    childList: true,
    subtree: true,
  });
}

// Run this function after the main SearchStax script loads.
window.onload = (event) => {
  // ... any existing onload code ...
  overrideInputPlaceholder();
};

Replace Translated Search Placeholder... with your own text.

Adapting for Multiple Languages

Like the afterSearch hook, you can adapt this solution for a multi-language site by using a translation function. 

function overrideInputPlaceholder() {
  const observer = new MutationObserver((mutationsList, observer) => {
    const input = document.getElementById("searchstax-search-input");
    if (input) {
      const currentLanguage = <YOUR_LANGUAGE_DETECTION_LOGIC>; // e.g., 'de' for German
      const translatedString = <YOUR_TRANSLATION_FUNCTION>('Search Placeholder', currentLanguage); // e.g., "Suche..."

      input.placeholder = translatedString;
      observer.disconnect();
    }
  });

  observer.observe(document.body, {
    childList: true,
    subtree: true,
  });
}

window.onload = (event) => {
  overrideInputPlaceholder();
};

In this version:

  • <YOUR_LANGUAGE_DETECTION_LOGIC> should be replaced with the code you use to determine the current page language.
  • <YOUR_TRANSLATION_FUNCTION> should be replaced with a call to your site's internationalization (i18n) library or a lookup from a translation object.

Verify Your Changes

To confirm that the solution is working:

  1. Add the overrideInputPlaceholder function and the window.onload call to your search page's template.
  2. Refresh your search page in the browser.
  3. Confirm that the search input box now displays your custom placeholder text before you've typed a query.
Articles in this section