Javascript API Reference
Just getting started? Learn how to embed the search interface on your site.
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-storkattributes 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 --buildcommand. - 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 a user selects a search result from the list. 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.
#transformResultUrl • Function: (string) => string
Default: (url) => url
A function that will transform search result URLs before they get output to the DOM as clickable links in the dropdown menu.
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.