typesense-minibar

minibar is a fast 2kB autocomplete search bar for Typesense. It is an alternative to typesense-docsearch.js, Algolia DocSearch, InstantSearch, autocomplete-js, and typesense-js.

Features

• Dependency-free, vanilla JavaScript
• Small size, 2kB transfer size
• Progressive enhancement, works without JavaScript
• Responsive, mobile-first layout
• Accessible, keyboard navigation, arrow keys, close on Esc or outside click
• Fast, leverages preconnect (Resource Hints), LRU memory cache
• Easy to install, fully declarative via HTML (zero-code setup!)

Getting started

Demo

<form role="search" class="tsmb-form" action="https://duckduckgo.com"
      data-origin=""
      data-collection=""
      data-key="">
  <input type="search" name="q" placeholder="Search..." autocomplete="off">
  <input type="hidden" name="sites" value="example.org">
</form>

<script defer type="module" src="typesense-minibar.js"></script>
<link rel="stylesheet" href="typesense-minibar.css">

Distribution:

• jsDelivr (browse):
  typesense-minibar.js, typesense-minibar.css
• UNPKG (browse):
  typesense-minibar.js, typesense-minibar.css
• npm: typesense-minibar

  npm i --save typesense-minibar

  require('typesense-minibar');
  import 'typesense-minibar';

API

Configuration

• data-origin (Required): Base URL to your Typesense server.

  Include the https:// or http:// protocol, and (if non-default) the port number.

  Example: https://typesense.example.org

• data-collection (Required): Which collection to query.

  Equal to the "index_name" in your docsearch.config.json file. If you index your websites with something other than docsearch-scraper, set this to the name of your Typesense collection (Typesense API).

  Example: example_mine

• data-key (Required): Search-only API key (Typesense API).

  Example: write000less000do000more0

• [data-slash=true] (Optional): Focus the input field if the / slash key is pressed.

  When enabled, a keydown event listener is added to document. Key presses in <input> or <textarea> elements are safely ignored. If multiple search forms are initiatilised on the same page, the first has precedence.

  Set data-slash="false" to disable this feature.

• [data-group=false] (Optional): Group results under category headings.

  By default, search results render in a flat list, with the lvl0 field as the page title, where lvl0 typicaly selects h1, lvl1 selects h2, and so on.

  To group results by category, configure docsearch-scraper with lvl0 selecting the category (not the h1). And lvl1 should then instead select your h1 page titles.

  Set data-group="true" to enable this feature.

• [data-foot=false] (Optional): Include a "Search by Typesense" link in the footer.

  Set data-foot="true" to enable this feature. When enabled, a plaintext link is added, styled using the Typesense brand color.

  Include typesense-minibar-foot.css to render the official Typesense wordmark instead.

• [data-search-params=""] (Optional): Modify search query parameters.

  Each key-value pair will be added as a search query parameter, or will override the default value. This property must be a valid URL parameters sequence, e.g. "key1=value1&key2=value2".

  Refer to typesense-minibar.js for the default search query parameters. Refer to Typesense documentation for all the valid parameters.

• [data-no-results="No results for '{}'."] (Optional): The message to display when no results are found.

  The sequence of 2 curly brackets {} will be substituted with the queried text.

Styling and theming

The accompanying stylesheet exposes CSS variables that you can override to tweak styles, without writing custom CSS. Alternatively, you can target stable selectors based on the semantic HTML.

Refer to Style API for the CSS variable names and selectors.

Compatibility

typesense-minibar	typesense-server	typesense-docsearch-scraper
1.0.x	>= 0.24	0.6.0.rc1

Browser support

The below matrix describes support for the enhanced JavaScript experience. The HTML experience falls back to submitting a form to DuckDuckGo, and works in all known browsers (including IE 6 and Netscape Navigator).

Browser	Policy	Version
Firefox	Current and previous version, Current and previous ESR	Firefox 74+ (2020)
Chrome	Last three years	Chrome 80+ (2020)
Edge	Last three years	Edge 80+ (2020)
Opera	Last three years	Opera 67+ (2020)
Safari	Last three years	Safari 13.1 (2020)
iOS	Last three years	iOS 13.4 (2020)

^{Notable feature requirements: ES6 syntax, ES2020 Optional chaining, ES2022 Async functions, DOM NodeList-forEach.}

Practical implications:

OS	Supported from	Running
Android	Moto G4 (2016)	Android 7.0 with Chrome 80+
Android	Samsung Galaxy S7 (2016)	Android 7.0 - 8.0
Android	Samsung Galaxy A5 (2016)	Android 7.0
Android	Google Pixel 1 (2016)	Android 7.0
iOS	iPhone 6S (2015)	iOS 13.4 (2020) upto iOS 15 (2022)
Linux	Debian 9 Stretch (2018)	firefox-esr 91
Linux	Debian 10 Buster (2019)	firefox-esr 102, chromium 90)
Linux	Ubuntu 18.04 LTS (2018)	current firefox, current chromium-browser
macOS	OS X 10.9 Mavericks (2013-2016)	Firefox 78 ESR (2020) (Safari 7 default unsupported)
macOS	OS X 10.13 Mavericks (2017-2020)	Firefox 78 ESR (2020), Chrome 80+ (Safari 11 default unsupported)
macOS	OS X 10.15 Catalina (2019-2022)	Safari 13.1, Firefox 78 ESR (2020), Chrome 80+
Windows	Windows 7 (2009) or later	current Edge, current Firefox

Notes:

• Firefox release schedule
• iOS 16 dropped support
• Google Chrome requires Android 7.0 and macOS 10.13
• Firefox 48 last to support OS X 10.6-10.8
• Firefox 78 last to support OS X 10.9-10.11

Feedback

For questions, bug reports, or feature requests, use the Issue tracker.