Developing a Search UI with UI Kits

Updated

Stand up a minimal search UI with a SearchStax UI Kit. You'll rely on the official npm README for each kit and the accelerator sample pages for the exact component markup and configuration. You'll wire up an MVP Search App and confirm that searches return results from your index.

Prerequisites

Before you start, you'll need:

  • A SearchStax Site Search account
  • Access to the Dashboard
  • A Search App with indexed content
  • Your Search & Indexing endpoints—see Gather your configuration below.
  • Permission to modify your app's build and environment variables

Gather Your Configuration

You'll reference the same values in all frameworks:

  • searchURL: Your Search API select endpoint (/emselect)
  • suggesterURL: Your Auto‑Suggest API endpoint (/emsuggest)
  • searchAuth + authType: Your Read Only token or basic auth
  • trackApiKey: Your Analytics Tracking key
  • language: UI language code (if you use multiple languages)

SearchStax Site Search All APIs screen with Search and Update Endpoints and authentication tokens.page.

Tip: If you plan to use Related Searches or Geocoding, also note the Discovery and Geocoding endpoints and keys.

Note: Use Read Only credentials for client apps. Don't embed Read & Write credentials.

Choose Your Path

You have two fast ways to get up and running with UI Kits: run an accelerator page or install a UI kit and implement widgets. If you want to get started even faster, though, consider using the Hosted Search Experience for a completely pre-built search experience.

Path A: Run an Accelerator Page and Copy What You Need

JavaScript Accelerator page

Use a sample search page to see your own data. Update the config with your Select Endpoint ( /emselect), Auto-Suggest Endpoint ( /emsuggest), and Read Only token, then run it and emulate the patterns in your own app.

See below for a step-by-step guide to running the JavaScript accelerator page.

Run the JavaScript Accelerator Page

  1. Clone the repo in Terminal (Mac) or PowerShell (Windows). 

    git clone https://github.com/searchstax/searchstudio-ux-samples.git

  2. Go to the JavaScript accelerator page folder. 

     cd searchstudio-ux-samples\pages\js\searchstax-accelerator-page

  3. In your terminal, install dependencies. 

     npm install

  4. Start the local dev server.  

     npm run dev

    The console will show a local address (for example, http://localhost:5173 ).Terminal showing npm run dev starting Vite server v6.3.5 at http://localhost:5173/

  5. Open http://localhost:5173 (or the port number shown in your console) in your browser. You should see the sample search UI.
  6. Open the accelerator page’s config file (config.js) in a text editor, like Microsoft Visual Studio Code. Replace the following values with the values from your Search App under App Settings > Data Management > All APIs:
    • searchURL: your app’s Select Endpoint
    • suggesterURL: your app’s Update Endpoint
    • searchAuth: your app’s Read Only token
  7. Save changes and refresh your browser. Run a search to confirm that results come from your indexed content.
    SearchStax Site Search javascript Accelerator screen.

You can follow similar steps for the accelerator pages for other frameworks. Each accelerator page folder has a README file with installation instructions.

Path B: Install a UI Kit and Implement Widgets

Add the framework package from npm and follow the README to drop in Input, Results, Facets, Pagination, and other widgets.

Tip: For time-based facets (for example, months or days of the week), use the beforeFacetsRender callback in UI Kits implementations to apply chronological ordering before rendering. See JavaScript - Hooks, JavaScript - Facets Widget, React - Facets Widget, Angular - Facets Widget, and Vue - Facets Widget.

JavaScript UI Kit

Add Search Input and Results Widgets (JavaScript UI Kit)

Prerequisites

Before you start, you'll need:

  • A JavaScript project that uses Vite. If your project uses another bundler (for example, Webpack or Parcel), follow the same steps but configure imports in step 2 according to your bundler’s documentation.

Create an MVP JavaScript SearchStax Site Search page

Follow these steps to add an input box and results list to a page in your app.

  1. In the root of your JavaScript project, install the UI Kit in Terminal (Mac) or PowerShell (Windows). 

    npm install --save @searchstax-inc/searchstudio-ux-js 

  2. In vite.config.ts (or vite.config.js), add an alias so Vite can import the package stylesheet. 

    const { defineConfig } = require('vite');
const path = require('path');

// Work around package exports: deep CSS import alias
module.exports = defineConfig({
  resolve: {
    alias: {
      '@searchstax-inc/searchstudio-ux-js/dist/styles/mainTheme.css': path.resolve(
        __dirname,
        'node_modules/@searchstax-inc/searchstudio-ux-js/dist/styles/mainTheme.css'
      ),
    },
  },
});

  3. Create a new HTML page (e.g., searchstax-search.html), add the containers, and link your JS file at the bottom of the 

    <!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>SearchStax MVP Search</title>
</head>
<body>
  <!-- Containers where UI Kit widgets will render -->
  <h1>SearchStax Site Search MVP</h1>
  <div id="searchstax-input-container"></div>
  <div id="searchstax-results-container"></div>

  <!-- Load your JS file after the containers -->
  <script src="src/searchstax-search.js" type="module"></script>
</body>
</html>

  4. Create a JavaScript file for your new search page (e.g., searchstax-search.js), import the CSS and library, initialize it with your App endpoint and token values, and add widgets: 

    // Import UI Kit CSS from the package (resolved via Vite alias)
import '@searchstax-inc/searchstudio-ux-js/dist/styles/mainTheme.css';
import { Searchstax } from '@searchstax-inc/searchstudio-ux-js';
const searchstax = new Searchstax();

searchstax.initialize({
  language: "en",
  searchURL: "https://searchcloud-1-us-east-1.searchstax.com/29847/tutorialqacrawlerapi-5641/emselect",
  suggesterURL: "https://searchcloud-1-us-east-1.searchstax.com/29847/tutorialqacrawlerapi-5641_suggester/emsuggest",
  trackApiKey: "S8Chdn7j3HQA0G9M6oztj7FS4XMkX7bzXuZq7A0hI2s",
  searchAuth: "9a6f1b606dc700b4af156713a8b6f13a425558b0",
  authType: "token"
});

// Attach widgets to your containers
searchstax.addSearchInputWidget("searchstax-input-container", {
  suggestAfterMinChars: 3
});

searchstax.addSearchResultsWidget("searchstax-results-container", {});

    Replace placeholders with values from your Search App under App Settings Data Management All APIs.

  5. In Terminal (Mac) or PowerShell (Windows), start your local server. 

    npm run dev

    Terminal showing npm run dev starting Vite server v6.3.5 at http://localhost:5173/

  6. Open the local server URL in your browser (e.g., http://localhost:5173/searchstax-search.html). Enter a query. Confirm results from your indexed content appears in the results container.
    SearchStax results page showing query 'financial' with result 'Financial aid Q&A webinar' and description 'Live Q&A with advisors'

For more information about the JavaScript UI Kit, including code for other widgets like facets, sorting, related searches, and more, see https://www.npmjs.com/package/@searchstax-inc/searchstudio-ux-js.

Tips and Troubleshooting
  • Use this standalone page first. Once you see valid results, you can start moving code into your existing search page.
  • Make sure you’re using the Read Only token in client code, not the Read & Write token.
  • Container IDs must match exactly between your HTML and JavaScript files.
  • If your team uses env files, prefer env vars for tokens and endpoints. Don’t hard-code secrets in source.
  • authType must match your App’s auth mode. If your App uses basic auth, don’t expose credentials in the browser—use a server proxy.
  • New Apps may show empty suggestions until analytics data accumulates.
  • Common HTTP errors include:
    • 401/403: bad token or wrong auth type
    • 404: wrong endpoint path
    • 429: account temporarily locked for over-usage

For more information about the JavaScript UI Kit, see @searchstax-inc/searchstudio-ux-js.

React UI Kit

Add Search Input and Results Widgets (react/Next.js UI Kit)

Prerequisites

Before you start, you'll need: 

  • A React app with a bundler (Turbopack, Vite, Next.js, CRA, or equivalent). This tutorial uses Turbopack.
  • Your App's endpoints and Read Only key. 
Create an MVP react SearchStax Site Search Page

Follow these steps to add an input box and results list to a React or Next.js page.

  1. Install in the folder that contains package.json. 

    npm install --save @searchstax-inc/searchstudio-ux-react

  2. Use the app router to create a dedicated page for testing. 

    app/searchstax-search/page.jsx   // or page.tsx if your project uses typescript

  3. Load the SearchStax stylesheet in your layout file (for global styles) or directly to the page where you’ll be adding SearchStax widgets. In the example below, we load the SearchStax stylesheet globally via a link tag in app/layout.jsx. This avoids module resolution issues with the package’s CSS export and keeps the MVP setup simple. 

    export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <head>
        <link
          rel="stylesheet"
          href="https://cdn.jsdelivr.net/npm/@searchstax-inc/searchstudio-ux-js@4.1.5/dist/styles/mainTheme.css"
        />
      </head>
      <body className={`${geistSans.variable} ${geistMono.variable}`}>
        {children}
      </body>
    </html>
  );
}

  4. Open your dedicated testing page (e.g., searchstax-search/page.jsx). Import the SearchStax React UI Kit, import SearchStax CSS, and render search input and results widgets. 

    "use client";
import { SearchstaxWrapper, SearchstaxInputWidget, SearchstaxResultWidget } from "@searchstax-inc/searchstudio-ux-react";

export default function SearchstaxSearchPage() {
  const config = {
    language: "en",
    searchURL:
      "https://searchcloud-1-us-east-1.searchstax.com/29847/tutorialqacrawlerapi-5641/emselect",
    suggesterURL:
      "https://searchcloud-1-us-east-1.searchstax.com/29847/tutorialqacrawlerapi-5641_suggester/emsuggest",
    trackApiKey: "S8Chdn7j3HQA0G9M6oztj7FS4XMkX7bzXuZq7A0hI2s",
    searchAuth: "9a6f1b606dc700b4af156713a8b6f13a425558b0",
    authType: "token",
  };

  return (
    <main style={{ padding: 24 }}>
      <h1>SearchStax Site Search MVP</h1>
      <SearchstaxWrapper
        language={config.language}
        searchURL={config.searchURL}
        suggesterURL={config.suggesterURL}
        trackApiKey={config.trackApiKey}
        searchAuth={config.searchAuth}
        authType={config.authType}
        initialized={() => {}}
      >
        <SearchstaxInputWidget suggestAfterMinChars={3} />
        <SearchstaxResultWidget />
      </SearchstaxWrapper>
    </main>
  );
}

  5. In Terminal (Mac) or PowerShell (Windows), start your local server. 

    npm run dev
  6. Open the local server URL in your browser (e.g., http://localhost:3000/searchstax-search.html). Enter a query. Confirm results from your indexed content appears in the results container.

For more information about the React UI Kit, see @searchstax-inc/searchstudio-ux-react.

Angular UI Kit

Add Search Input and Results Widgets (Angular UI Kit)

Prerequisites

Before you start, you'll need: 

Create an MVP Angular SearchStax Site Search Page

Follow these steps to add an input box and results list to an Angular page.

  1. Install. 

    npm install --save @searchstax-inc/searchstudio-ux-angular

  2. Import the module. Make sure your module imports SearchstudioUxAngularModule. 

    import { SearchstudioUxAngularModule } from '@searchstax-inc/searchstudio-ux-angular';

@NgModule({
  imports: [SearchstudioUxAngularModule],
})
export class AppModule {}

  3. Add the following code to your ts file and fill config. 

    config = {
searchURL: '',
suggesterURL: '',
trackApiKey: '',
searchAuth: '',
authType: 'basic',
relatedSearchesAPIKey: '',
relatedSearchesURL: '',
analyticsBaseUrl: 'https://analytics-us-east.searchstax.com'
}

beforeSearch(props: ISearchObject) {
// gets searchProps, if passed along further search will execute, if null then event gets canceled
// props can be modified and passed along
const propsCopy = { ...props }
// propsCopy.term = propsCopy.term;
return propsCopy
}
afterSearch(results: ISearchstaxParsedResult[]) {
const copy = [...results]
// copy.splice(0, 1);
return copy
}

afterAutosuggest(result: ISearchstaxSuggestResponse) {
const copy = { ...result }
return copy
}

beforeAutosuggest(props: ISearchstaxSuggestProps) {
// gets suggestProps, if passed along further autosuggest will execute, if null then event gets canceled
// props can be modified and passed along
const propsCopy = { ...props }
// propsCopy.term = propsCopy.term + '222';
return propsCopy
}

afterLinkClick(results: ISearchstaxParsedResult): ISearchstaxParsedResult {
// gets result that was clicked, if passed along further functions will execute, if null then event gets canceled
const copy = { ...results }

return copy
}

initialized(searchstax: Searchstax) {
console.log('searchstax', searchstax);
}

    Note: Current UI Kits versions can expose the full raw /emselect response in afterSearch. Use it when you need response data beyond the parsed result list for custom UI behavior.

    Replace the empty strings with your App's endpoints and tokens.

  4. Wrap your template and add widgets. 

     <div>
<app-searchstax-wrapper
[searchURL]="config.searchURL"
[suggesterURL]="config.suggesterURL"
[trackApiKey]="config.trackApiKey"
[searchAuth]="config.searchAuth"
[beforeSearch]="beforeSearch"
[afterSearch]="afterSearch"
(initialized)="initialized($event)"
>
<div class="searchstax-page-layout-container">
<app-searchstax-input
[afterAutosuggest]="afterAutosuggest"
[beforeAutosuggest]="beforeAutosuggest"
[suggestAfterMinChars]="3"
></app-searchstax-input>
<div class="search-details-container">
<app-searchstax-search-feedback></app-searchstax-search-feedback>
<app-searchstax-search-sorting></app-searchstax-search-sorting>
</div>
<div class="searchstax-page-layout-facet-result-container">
<div class="searchstax-page-layout-facet-container">
<app-searchstax-search-facets
[facetingType]="'showUnavailable'"
[itemsPerPageDesktop]="2"
[itemsPerPageMobile]="99"
></app-searchstax-search-facets>
</div>
<div class="searchstax-page-layout-result-container">
<app-searchstax-external-promotions></app-searchstax-external-promotions>
<app-searchstax-results
[afterLinkClick]="afterLinkClick"
></app-searchstax-results>
<app-searchstax-related-searches
[relatedSearchesURL]="config.relatedSearchesURL"
[relatedSearchesAPIKey]="config.relatedSearchesAPIKey"
></app-searchstax-related-searches>

<app-searchstax-search-pagination></app-searchstax-search-pagination>
</div>
</div>
</div>
</app-searchstax-wrapper>
</div>

If nothing renders: Check that the wrapper is present, initialize-equivalent inputs are provided via [searchURL], [suggesterURL], [trackApiKey], [searchAuth], and your IDs/props match the examples.

For more information about the Angular UI Kit, see @searchstax-inc/searchstudio-ux-angular.

Vue UI Kit

Add Search Input and Results Widgets (Vue UI Kit)

Prerequisites

Before you start, you'll need: 

Create an MVP Vue SearchStax Site Search Page

Follow these steps to add an input box and results list to a Vue page.

  1. Install. 

    npm install --save @searchstax-inc/searchstudio-ux-vue

  2. Add analytics script to . 

    <script type="text/javascript">
      var _msq = _msq || []; //declare object
      var analyticsBaseUrl = '<https://analytics-us-east.searchstax.co>';
      (function () {
        var ms = document.createElement('script');
        ms.type = 'text/javascript';
        ms.src = '<https://static.searchstax.co/studio-js/v3/js/studio-analytics.js>';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(ms, s);
      })();
    </script>

  3. Import and register components. 

    import { SearchstaxWrapper, SearchstaxInputWidget, SearchstaxResultWidget } from '@searchstax-inc/searchstudio-ux-vue';

Vue.component('SearchstaxWrapper', SearchstaxWrapper);
Vue.component('SearchstaxInputWidget', SearchstaxInputWidget);
Vue.component('SearchstaxResultWidget', SearchstaxResultWidget);

  4. Initialize config. 

     sampleConfig = {
    language: "en",
    model: "Main Profile",
    searchURL: "",
    suggesterURL: "",
    trackApiKey: "",
    searchAuth: "",
    authType: "basic",
    router: {
      enabled: true,
      routeName: "searchstax",
      title: (result: ISearchObject) => {
        return "Search results for: " + result.query;
      },
      ignoredKeys: [],
    },
    hooks: {
      beforeSearch: function (props: ISearchObject) {
        const propsCopy = { ...props };
        return propsCopy;
      },
      afterSearch: function (results: ISearchstaxParsedResult[]) {
        const copy = [...results];
        return copy;
      },
    }
  };

    Note: Depending on your UI Kit version, afterSearch can also provide access to the full raw /emselect response. Use it for advanced filters, custom date logic, or other UI behavior based on response metadata.

    Replace the empty strings with your App's endpoints and tokens.

  5. Add widgets to your page 

     <SearchstaxWrapper
    :language="sampleConfig.language"
    :model="sampleConfig.model"
    :searchURL="sampleConfig.searchURL"
    :suggesterURL="sampleConfig.suggesterURL"
    :trackApiKey="sampleConfig.trackApiKey"
    :searchAuth="sampleConfig.searchAuth"
    :authType="sampleConfig.authType"
    :router="sampleConfig.router"
    :beforeSearch="sampleConfig.hooks.beforeSearch" // callback function to intercept search object before search is fired
    :afterSearch="sampleConfig.hooks.afterSearch" //  callback function to handle results after search is fired
  >
    <template #default>
      <div class="searchstax-page-layout-container">
        <SearchstaxInputWidget
          :afterAutosuggest="afterAutosuggest"
          :beforeAutosuggest="beforeAutosuggest"
          :suggestAfterMinChars="3"
        >
        </SearchstaxInputWidget>
        <div class="search-details-container">
          <SearchstaxSearchFeedbackWidget></SearchstaxSearchFeedbackWidget>
          <SearchstaxSortingWidget></SearchstaxSortingWidget>
        </div>
        <div class="searchstax-page-layout-facet-result-container">
          <div class="searchstax-page-layout-facet-container">
            <SearchstaxFacetsWidget
              :facetingType="'or'"
              :itemsPerPageDesktop="3"
              :itemsPerPageMobile="99"
            >
            </SearchstaxFacetsWidget>
          </div>
          <div class="searchstax-page-layout-result-container">
            <div id="searchstax-external-promotions-layout-container"></div>
            <SearchstaxResultWidget :afterLinkClick="afterLinkClick">
            </SearchstaxResultWidget>
            <div id="searchstax-related-searches-container"></div>
            <SearchstaxPaginationWidget>
            </SearchstaxPaginationWidget>
          </div>
        </div>
      </div>
    </template>
  </SearchstaxWrapper>

If nothing renders, verify that SearchstaxWrapper wraps the widgets, config props are set, and styles are imported.

For more information, see @searchstax-inc/searchstudio-ux-vue.

Choose a Version

You can choose how updates to your chosen UI Kit are applied by pinning exact versions in package.json or by installing with @ (for example, @4.1.5). See the links in Path B: Install a UI Kit and implement widgets for version history and changelogs.

What's Next

You now have an MVP custom UI calling core APIs. Next, review the pre-launch checklist to make sure your configuration, indexing, and analytics tracking are ready for production.

Articles in this section