Search Configuration

All options here are provided through the infisearch.init function exposed by the search bundle.

There are 2 categories of options, the first related to the user interface, and the other search functionalities.

Search UI Options

Search UI options are organised under the uiOptions key:

    uiOptions: {
        // ... options go here ...

Site URL


  • Example: '/' or ''

This option allows InfiSearch to construct a link to the page for search result previews. This is done by appending the relative file path of the indexed file.

Unless you are providing all links manually (see Linking to other pages), this URL must be provided.

Input Element

OptionDefault ValueDescription
input'infi-search'id of the input element or a HTML element reference
inputDebounce100debounce time of keystrokes to the input element
preprocessQuery(q) => qany function for preprocessing the query. Can be used to add a field filter for example.

The input element is required in most cases. Its behaviour depends on the UI mode.

UI Mode

mode: 'auto'

The search UI provides 4 main different behaviours.

autoThis uses the fullscreen mode for a mobile device, and dropdown otherwise.
This adjustment is rerunned whenever the window is resized.
dropdownThis wraps the provided input element in a wrapper container, then creates a dropdown next to house InfiSearch’s UI.
fullscreenThis creates a distinct modal (with its own search input, close button, etc.) and appends it to the page <body>.

If the input element is specified, a click handler is attached to open this UI so that it functions as a button. For default keyboard accessibility, some minimal and overidable styling is also applied to this button.

This UI can also be toggled programatically, removing the need for the input.
targetThis option is most flexible, and is used by the mdBook plugin (this documentation).

Search results are then output to a custom target element of choice.

Use the following buttons to try out the different modes. The default in this documentation is target.

UI Mode Specific Options

There are also several options specific to each mode. dropdown and fullscreen options are also applicable to the auto mode.

dropdowndropdownAlignment'bottom-end''bottom' or 'bottom-start' or 'bottom-end'.

The alignment will be automatically flipped horizontally to ensure optimal placement.
fullscreenfsContainer<body>id of or an element reference to attach the modal to.
fullscreenfsScrollLocktrueScroll locks the body element when the fullscreen UI is opened.
targettargetundefinedid of or an element reference to attach the UI.

General Options

tiptrueShows the advanced search tips icon on the bottom right.
maxSubMatches2Maximum headings to show for a result preview.
resultsPerPage10Number of results to load when ‘load more’ is clicked.
useBreadcrumbfalsePrefer using the file path as the result preview’s title. This is formatted into a breadcrumb, transformed to Title Case.

Example: 'documentation/userGuide/my_file.html'Documentation » User Guide » My File.

Setting Up Enum Filters ∀

Enum fields you index can be mapped into UI multi-select dropdowns. In this documentation for example, Mdbook’s section titles “User Guide”, “Advanced” are mapped.

Setup bindings under uiOptions like so:

multiSelectFilters: [
    fieldName: 'partTitle',  // name of field definition
    displayName: 'Section',  // UI header text
    defaultOptName: 'None',
    collapsed: true,         // only the first header is initially expanded

Documents that do not have an enum value are assigned an internal default enum value. The option text of this enum value to show is specified by defaultOptName.

Setting Up Numeric Filters and Sort Orders

Indexed numeric fields can be mapped into minimum-maximum filters of <input type="number|date|datetime-local" />, or used to create custom sort orders.

Minimum-Maximum Filters

numericFilters: [
    fieldName: 'pageViewsField',
    displayName: 'Number of Views',
    type: 'number' | 'date' | 'datetime-local',
    // Text above date, datetime-local filters and placeholder text for number filters
    // Also announced to screenreaders
    minLabel: 'Min',
    maxLabel: 'Max',

Sorting by Numbers, Dates

sortFields: {
  // Map of the name of your numeric field to names of UI options
  price: {
    asc: 'Price: Low to High',
    desc: 'Price: High to Low',

Manually Showing / Hiding the Fullscreen UI

Call the showFullscreen() and hideFullscreen() functions returned by the infisearch.init to programatically show/hide the fullscreen search UI.

// These methods can be used under mode="auto|fullscreen"
const { showFullscreen, hideFullscreen } = infisearch.init({ ... });

Client Side Routing

To override the link click handler, use the specially provided parameter onLinkClick.

uiOptions: {
  onLinkClick: function (ev) {
     By default, this function is a thunk.
     Call ev.preventDefault() and client-side routing code here.
     Access the anchor element using "this".

Changing The Mobile Device Detection Method

If the client is a “mobile device”, the fullscreen UI is used under mode='auto'. The check is done with a media query, which can be overwritten:

uiOptions: {
  // Any function returning a boolean
  isMobileDevice: () =>
    window.matchMedia('only screen and (max-width: 768px)').matches,

Search Functionality Options

The options regarding search functionalities itself are rather brief:

    searcherOptions: {
        // URL of output directory generated by the CLI tool
        url: '',

        // ---------------------------------------------------------------
        // Optional Parameters
        maxAutoSuffixSearchTerms: 3,
        maxSuffixSearchTerms: 5,

        useQueryTermProximity: true,

        // Maximum number of results (unlimited if null).
        resultLimit: null,

        // ------------------------------
        // Caching Options

        // Caches **all** texts of storage=[{ "type": "text" }] fields up front,
        // to avoid network requests when generating result previews.
        // Discussed in the "Larger Collections" chapter.
        cacheAllFieldStores: undefined,

        // Any index chunk larger than this number of bytes
        // will be persistently cached once requested.
        plLazyCacheThreshold: 0,
        // ------------------------------

        // ---------------------------------------------------------------

maxAutoSuffixSearchTerms = 3

Stemming is turned off by default. This does mean a bigger dictionary (but not too much usually), and lower recall, but much more precise searches.

To keep recall up, an automatic wildcard suffix search is performed on the last query term of a free text query, and only if the query does not end with a whitespace (an indicator of whether the user has finished typing).

maxSuffixSearchTerms = 5

This controls the maximum number of terms to search for manual wildcard suffix searches.

Term Proximity Ranking

useQueryTermProximity = true

If positions are indexed, document scores are also scaled by how close query expressions or terms are to each other. This boosts result relevance significantly.

Caching Options (Advanced)

This is discussed more in the chapter on larger collections.