Javascript Reference

The Stork Javascript library exposes a single global variable, stork, which has five methods. The method you'll most likely use is the register() method, which takes three parameters:

stork.register(name, url, options)

This method initializes Stork, downloads your search index, and harnesses the DOM to make the search elements interactive.

  • The name parameter is a string that defines which HTML elements Stork should attach to. This name should be the same as the name you put in the data-stork attributes in your input and output elements.
  • The url parameter is a string that contains the URL of your index file. The file at this URL should be a publicly-available Stork index file generated by the stork --build command.
  • The options parameter is an optional object whose available configuration keys are defined below. None of the keys are required.

Registration Options

showProgress Boolean

Default: true

When true, Stork will display a progress bar in the input field as the index is loading. When false, that progress bar will not be rendered.

printIndexInfo Boolean

Default: false

If this is set to true, Stork will print information about the search index to the console when it has successfully loaded.

showScores Boolean

Default: false

If this is set to true, Stork will display the scores it computes for each result and excerpt, used for result ordering.

minimumQueryLength Number

Default: 3

The minimum length a query must be to request results from the index. If this is smaller than the minimum_indexed_substring_length in your index, Stork will make unnecessary search requests.

onQueryUpdate Function: (query, results) => void

Default: undefined

A callback function that will be called every time the search query updates and new results are displayed. This function is called with two arguments: the string typed into the search field, and an array of Result objects.

onResultSelected Function: (query, result) => void

Default: undefined

A callback function that will be called every time the search query updates and new results are displayed. This function is called with two arguments: the string typed into the search field, and the Result object the user selected. If you return a Promise from this function, Stork will await that promise before changing the window location.

onResultsHidden Function: () => void

Default: undefined

A callback function that will be called when the user hides the search results, either by pressing the [x] button in the interface or by pressing esc once.

onInputCleared Function: () => void

Default: undefined

A callback function that will be called when the user clears the search input field, either by pressing the [x] button in the interface or by pressing esc twice.

The Result Object

entry An Entry object

The file represented by the result.

excerpts Array of Excerpt objects

Each excerpt visible to the user in the search interface.

score Number

The "relevance" score Stork computed for the given entry. Used to order the results for a given query

The Entry Object

title String

The title of the document

url String

The URL to where the search result links

fields Object

A set of key-value pairs passed through from the file object in the Configuration File. Can be used to pass arbitrary string-based metadata from the index at build time to the JS environment at runtime.

The Excerpt Object

text String

The excerpt of text from the original file that contains the user's search query. Usually displayed in a list

score Number

The "relevance" score Stork computed for the given entry. Used to order all excerpts within a given result.

fields Object

Default: 5

A set of key-value pairs passed through from the file object in the Configuration File. Can be used to pass arbitrary string-based metadata from the index at build time to the JS environment at runtime.

Other methods

There are more methods on the stork global variable that afford more control over loading the WASM binary and/or search index, attaching Stork into your DOM, or running searches. For more information on how to use these methods, read the advanced JavaScript Usage documentation.

stork.initialize(wasm_url)

Initializes the WASM library. The optional wasm_url parameter lets you specify a URL from which the WASM binary should be downloaded.

stork.downloadIndex(name, url, options)

Downloads a search index file and makes it addressable from the attach() or search() methods by naming it. The three parameters here are identical to the stork.register() parameters.

stork.attach(name)

Harnesses existing DOM elements to provide as-you-type search results for a downloaded index.

stork.search(name, query)

Runs a search and returns an array of Result objects.

© 2019–2021

Stork is built and shepherded by James Little, who's really excited that you're checking it out. If you have any questions or comments, feel free to tweet at him or open an issue on Github.

This site is open source. Please file a bug or open a PR if you see something confusing or incorrect. PRs are always welcome!

Logo by Bruno Monts. Please contact James Little before using the Stork logo. Thanks to Bruno and the fission.codes team for making this logo happen.