Hide Navigation

Javascript API Reference

Just getting started? Learn how to embed the search interface on your site.

The stork object exposed by the Stork Javascript library has one method: stork.register(). This method takes three parameters, though only the first two are required:

stork.register(name, url, options)
  • The name parameter is a string that defines which elements in your HTML the Stork library should attach to. This name should be the same as the name you put in the data-stork attributes.
  • 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

KeyTypeDefaultDescription
showProgressBooleantrueWhen 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.
printIndexInfoBooleanfalseIf this is set to true, Stork will print information about the search index to the console when it has successfully loaded.
showScoresBooleanfalseIf this is set to true, Stork will display the scores it computes for each result and excerpt, used for result ordering.
minimumQueryLengthNumber3The 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.
onQueryUpdateFunctionundefinedA 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.
onResultSelectedFunctionundefinedA 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.

The Result Object

KeyTypeDescription
entryAn Entry objectThe file represented by the result.
excerptsArray of Excerpt objectsEach excerpt visible to the user in the search interface.
scoreNumberThe "relevance" score Stork computed for the given entry. Used for result ordering for a given query.

The Entry Object

KeyTypeDescription
titleStringThe title of the document
urlStringThe URL to where the search result links
fieldsObjectA 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

KeyTypeDescription
textStringThe excerpt that contains the given search query. Usually displayed in a list.
scoreNumberThe "relevance" score Stork computed for the given entry. Used for excerpt ordering within all excerpts in a given result.
fieldsObjectA 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.

© 2019–2020

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 get in touch or open an issue on Github.

This site is also on Github; feel free to put up a PR or open an issue if you see something worth changing.