StaticSearch JavaScript search API

You can create whatever input and output functionality or styling you require by directly calling the StaticSearch JavaScript API. You can use it if the web component and bind module do not provide features you require.

staticsearch.find() method #

The staticsearch.find(<term>[, <fuzzy>]) method returns an array of results for a specific search term:

JavaScript excerpt

import { staticsearch } from '/search/staticsearch.js';

const result = await staticsearch.find('my search query');

The second fuzzy argument returns a number words for partial string matches (default 6). Using a fuzzy value of 1 looks for exact word matches:

JavaScript excerpt

const result = await staticsearch.find('my search query', 1);

The returned result holds an array of page objects sorted from highest to lowest relevancy. Each page object has the properties:

example result

[
  {
    "id": 42,
    "url": "/news/search-engine-optimization/",
    "title": "Do Publican sites rank better?",
    "description": "Do static sites rank better in search engines?",
    "date": "2025-01-31",
    "words": 1234,
    "relevancy": 21,
    "found": 1
  },
  {
    "id": 55,
    "url": "/docs/recipe/feeds/txt-sitemap/",
    "title": "Create a text sitemap",
    "description": "How to output a list of all pages for search engines.",
    "date": "2025-02-01",
    "words": 954,
    "relevancy": 12,
    "found": 0.5
  },
  {
    "id": 22,
    "url": "/news/site-performance/",
    "title": "Are static sites fast?",
    "description": "Static sites typically perform better than others.",
    "date": "2025-02-22",
    "words": 222,
    "relevancy": 2,
    "found": 0.5
  }
]

staticsearch.fetchTimeout property #

StaticSearch permits up to five seconds to load an index file. This should be adequate for most sites, but you can specify any .fetchTimeout limit in milliseconds, e.g.

JavaScript excerpt

// set fetch timeout to 10 seconds
staticsearch.fetchTimeout = 10000;

StaticSearch events #

Whenever a search runs, StaticSearch triggers events on the page’s document object. This may be useful when:

• you’d rather not await the .find() Promise
• you want to show the same search result in more than one element.

staticsearch:find event #

This event triggers when staticsearch.find() runs (before results are available). The search term is available in the event object’s detail.search property:

JavaScript excerpt

// search started
document.addEventListener('staticsearch:find', e => {

  // get search term
  const { search } = e.detail;

  console.log(`searching for "${ search }"`);

});

staticsearch:result event #

This event triggers when search results are ready. The search term and results array are available in the event object’s detail.search and detail.result properties:

JavaScript excerpt

// search result available
document.addEventListener('staticsearch:result', e => {

  // get search term and result array
  const { search, result } = e.detail;

  console.log(`${ result.length } pages found for "${ search }"`);

});

Re-run the indexer #

Once you have added StaticSearch functionality to your static site’s templates, you should re-run the indexer to ensure word indexes are up-to-date.