Live suggestions

Offering autocomplete and/or autosearch is one of the most important ways to improve the search experience for your visitors. Autocomplete suggests search terms as users type, while autosearch shows actual results in real time.

As mentioned in the Introduction, Pandosearch does not provide prebuilt search UI components. Since websites vary greatly in technology and structure, we focus on giving you the tools and examples to implement search in your own environment.

This guide covers how to implement live suggestions using Pandosearch API responses with modern, browser-native JavaScript.

Notes on approach

  • We refer to the "visitor" as someone searching on your site, and "you" as the developer integrating Pandosearch.
  • "Website" here may also mean web apps or mobile frontends.
  • Code examples use vanilla JavaScript compatible with all major modern browsers, no frameworks or build steps required.
  • Examples are intentionally minimal to highlight key concepts. Adjust them as needed for your tech stack.
  • For demo purposes, this guide uses our documentation site at developer.pandosearch.com as the collection.

Why use live suggestions?

Pandosearch can instantly return two types of data:

  • suggestions — potential search terms based on indexed data.
  • hits — actual results for a given query.

Live feedback while typing improves both usability and effectiveness:

  • Typing “pa” can show “pandosearch” instantly.
  • Only indexed terms are suggested—no dead-end searches.
  • Typos are reduced by suggesting correct terms.
  • Instant hits let users find content faster, often without needing to load a full results page.

We strongly recommend adding live suggestions when implementing Pandosearch to boost user experience and search performance.

Example implementation

As an example, we'll be implementing live suggestions for our developer.pandosearch.com collection. When following along, just replace this with your own Pandosearch collection name and you'll get suggestions based on your own data.

Let's start with the end result. Just type "p" and "a" in the search box below to see suggestions and hits appear:

Suggestions:
    Hits:

      So what is happening here? Let's walk through the code step-by-step.

      We start with some basic search form HTML:

      <form autocomplete="off">
  <fieldset>
    <input type="search" id="search-input" placeholder="Search..." />
    <div>Suggestions:</div>
    <ul id="suggestions-list"></ul>
    <div>Hits:</div>
    <ul id="hits-list"></ul>
  </fieldset>
</form>

      Some points of note about the HTML:

      • The form element normally has an action attribute pointing to the URL on which search results are displayed. As this is demo code, we do not have such a page here. In your implementation, you do need to set this attribute, as this enables people to still search even when live suggestions are not available. This can be very important for people using screen readers and it is also a general fallback in case your JavaScript code contains a bug or does not work for other technical reasons.
      • The fieldset, div and ul elements in the HTML do not have any meaning. They only provide a minimum layout for this demo and can safely be replaced by something more suitable for your situation.
      • The id attributes on the input and ul elements are used to attach event handlers and insert HTML elements using JavaScript. In your implementation you can use any kind of element selector you want.
      • The autocomplete="off" attribute is needed to prevent browsers from also showing live suggestions based on your browser history. If you do not set this attribute, the browser's suggestions will interfere with the suggestions coming from Pandosearch.

      The rest of the code is a <script> element with the JavaScript needed to listen to keyboard events, fetch API data, and finally convert this data to clickable HTML elements:

      // Get relevant DOM elements
const input = document.getElementById('search-input');
const suggestionsList = document.getElementById('suggestions-list');
const hitsList = document.getElementById('hits-list');

// Debounce to reduce API traffic
function debounce(fn, delay) {
  let timeout;
  return (...args) => {
    clearTimeout(timeout);
    timeout = setTimeout(() => fn(...args), delay);
  };
}

// Fetch suggestions + hits from Pandosearch
async function fetchSuggestionsAndHits(query) {
  const url = `https://public.pandosearch.com/developer.pandosearch.com/suggest?q=${encodeURIComponent(query)}`;

  try {
    const response = await fetch(url);
    if (!response.ok) throw new Error('Request failed');
    return await response.json();
  } catch (err) {
    console.error('Fetch error:', err);
    return { suggestions: [], hits: [] };
  }
}

// Render list items
function renderList(container, items, formatItem) {
  container.innerHTML = '';
  items.forEach(item => {
    const li = document.createElement('li');
    li.innerHTML = formatItem(item);
    container.appendChild(li);
  });
}

// Update UI on input
const handleInput = debounce(async (event) => {
  const query = event.target.value.trim();
  const { suggestions, hits } = await fetchSuggestionsAndHits(query);

  renderList(suggestionsList, suggestions, suggestion =>
    `<a href="?q=${encodeURIComponent(suggestion.text)}">${suggestion.text}</a>`
  );

  renderList(hitsList, hits, hit =>
    `<a href="${hit.url}">${hit.title}</a>`
  );
}, 200);

input.addEventListener('input', handleInput);

      Let's break this down part by part:

      • First the relevant DOM elements are selected.
      • A debounce function is declared to avoid unnecessary API calls.
      • fetchSuggestionsAndHits handles the API request and response.
      • renderList converts the API response data to HTML list items.
      • handleInput is the input event handler tying everything together.

      The code should be largely self-explanatory. Some additional remarks:

      • The debounce timeout of 200 milliseconds may have to be adjusted to your specific situation.
      • For suggestions: the ?q=... search results page link is for illustration purposes only and should be replaced with the correct search results page path for your website.

      API response data explained

      With the code above, on every character you type, the Pandosearch Suggest API action is called.

      For this demo, the following JSON response data is of interest:

      1. suggestions – A list of search query suggestions based on the input given. For "pa", this will include "pandosearch" and other words starting with "pa".
      2. hits – A list of the most relevant documents Pandosearch has found for the search query "pa". In this demo, this will include developer documentation pages with "pa" in the title and/or body content.

      Real-world usage

      And with this done, we have a fully working live suggestions implementation. Just take a look at the source of this page to see all source code in one place.

      You can freely copy-paste all of it and use it on your website, but it might be a good idea to first read the following section.

      When implementing live suggestions on your website, here are a couple of additional things you might want to consider:

      • While our keyup event handler and includes debouncing, it is not fine-tuned to our needs. The API is called on every keystroke, including Shift, Ctrl, and other non-character keys. Although Pandosearch is built for heavy request loads, firing unnecessary requests may still negatively impact user experience depending on your visitors' network connection quality.
      • Also not included in the example are key bindings for the up and down arrow keys and Enter key for navigating and selecting suggestions and hits. Adding this greatly improves the user experience for users with a keyboard as their preferred method for navigation.
      • We did not touch the subject of accessibility, as it would distract from the main message of this guide. Depending on your domain, you may need to include this when implementing live suggestions. The Accessibility pages on MDN are a great starting point for further research.
      • Styling (CSS) is intentionally left up to you, as you know best what fits within the overall design of your website.

      Given all the above, you may want to consider an existing autocomplete widget or library, either in vanilla JavaScript or specifically built for the JavaScript framework(s) you already use. This can be a great choice, as things like sophisticated keyboard event handling and accessibility support are often built-in, potentially saving you a ton of work.

      When investigating this option, do make sure you look for the ability to customize the live suggestions HTML output, specifically in the following ways:

      • Ensure that you are able to generate two different lists of HTML elements (suggestions and hits). Some autocomplete widgets assume homogeneous data, which can make it hard or even impossible to show Pandosearch suggestions and hits simultaneously.
      • Ensure that you are able to show direct hyperlinks in the live suggestions. Some autocomplete widgets assume that you only want to show suggestions to use as an input value. In case of instant hits, this is not enough, as they contain a direct link to a webpage and not a suggestion for a search query.

      And that's it for this guide. Up to the next one: search results.