This documentation demonstrates how to integrate the ZIR Semantic Search widget into a Javascript application.

For full :page_facing_up: documentation, visit the online documentation.

The search widget connects to a corpus or corpora through API keys. It presents the user with a polished, customizable text box for entering queries, and handles results and errors using callback methods. It also exposes a search(query) method that enables programmatic interaction with the search.

:bulb: Getting Started

Begin by installing the CoreJS package for semantic search:

npm install @zir-ai/searchbox-corejs

The snippet below shows how to initialize the search box and embed it into
a page. This snippet also demonstrates ZIR Semantic Search's ability to
concurrently query multiple corpora and blend the results.

<script>
  let widget = zirSearch.createSearch(
    "zqt_cKg6-joMkEsOa1EbNS-MQefDdC3I7Ct_g3tr2Q", // api key
    1890073338,                                   // customer id
    [148, 157, 160],                              // array of corpus id's
    success,                                      // success function
    error,                                        // error function
    "./download.png",                             // custom icon
    20,                                           // number of results
    "Enter what you want to ask about",           // search placeholder
    false                                         // default focus
  );
  document.getElementById("anchor").appendChild(widget);

  function success(results) {
    // Process the results and display them on the page.
    console.log(results);
  }

  function error(err) {
    // Something went wrong. Show the user an appropriate error message.
    console.log(err);
  }
</script>

API

The zirSearch.createSearch method creates the search box widget, and returns
a component that can be inserted into the DOM of the host page.

A brief description of each method parameter is below:

Mandatory Parameters

1. apiKey: the API key linked to one or more corpora.
2. customerID: your account ID.
3. corpusID: an array of IDs of the corpora to be queried. This can range
   from a single corpus to an account-specific limit, which is generally five.
4. successFn: a callback function that is invoked when the search results are
   returned. Use this function to render individual results on the page.

Optional Parameters

1. errorFn: a callback function that is invoked when an error is encountered. This
   function should be used to render a readable error message for the user.
2. customIcon: the ZIR logo is shown in the search box by default. This can be
   altered by passing in the path to a replacement image.
3. numResults: the desired number of search results. ten results are returned by
   default. To alter this, pass in any positive integer value up to the
   maximum number allowed by your account.
4. placeholder: The placeholder text to be displayed in the search box.
5. focus: If set to true, the search box will receive focus when the page loads.

Pagination

Pagination can be setup using the zirSearch.createPagination(widget)
function. Once createPagination has been called, append the pagination widget
wherever desired in the DOM.

const pagination = zirSearch.createPagination(widget);
document.getElementById("pagination").appendChild(pagination);