bootstrap5-autocomplete

Autocomplete for Bootstrap 4/5

How to use

An ES6 autocomplete for your input using standards Bootstrap 5 (and 4) styles.

No additional CSS needed!

import Autocomplete from "./autocomplete.js";
Autocomplete.init();

Server side support

You can also use options provided by the server. This script expects a JSON response with the following structure:

{
    "optionValue1":"optionLabel1",
    "optionValue2":"optionLabel2",
    ...
}

or

[
  {
    "value": "server1",
    "label": "Server 1"
  },
  ...
]

Simply set data-server where your endpoint is located. The suggestions will be populated upon init except if data-live-server is set, in which case, it will be populated on type. A ?query= parameter is passed along with the current value of the searchInput.

Data can be nested in the response under the data key (configurable with serverDataKey).

Options

Options can be either passed to the constructor (eg: optionName) or in data-option-name format.

Name	Type	Description
showAllSuggestions	Boolean	Show all suggestions even if they don't match
suggestionsThreshold	Number	Number of chars required to show suggestions
maximumItems	Number	Maximum number of items to display
autoselectFirst	Boolean	Always select the first item
ignoreEnter	Boolean	Ignore enter if no items are selected (play nicely with autoselectFirst=0)
tabSelect	Boolean	Tab will trigger selection if active
updateOnSelect	Boolean	Update input value on selection (doesn't play nice with autoselectFirst)
highlightTyped	Boolean	Highlight matched part of the label
highlightClass	String	Class added to the mark label
fullWidth	Boolean	Match the width on the input field
fixed	Boolean	Use fixed positioning (solve overflow issues)
fuzzy	Boolean	Fuzzy search
startsWith	Boolean	Must start with the string. Defaults to false (it matches any position).
fillIn	Boolean	Show fill in icon.
preventBrowserAutocomplete	Boolean	Additional measures to prevent browser autocomplete
itemClass	String	Applied to the dropdown item. Accepts space separated classes.
activeClasses	Array	By default: ["bg-primary", "text-white"]
labelField	String	Key for the label
valueField	String	Key for the value
searchFields	Array	Key for the search
queryParam	String	Key for the query parameter for server
items	Array | Object	An array of label/value objects or an object with key/values
source	function	A function that provides the list of items
hiddenInput	Boolean	Create an hidden input which stores the valueField
hiddenValue	String	Populate the initial hidden value. Mostly useful with liveServer.
clearControl	String	Selector that will clear the input on click.
datalist	String	The id of the source datalist
server	String	Endpoint for data provider
serverMethod	String	HTTP request method for data provider, default is GET
serverParams	String | Object	Parameters to pass along to the server. You can specify a "related" key with the id of a related field.
serverDataKey	String	By default: data
fetchOptions	Object	Any other fetch options (https://developer.mozilla.org/en-US/docs/Web/API/fetch#syntax)
liveServer	Boolean	Should the endpoint be called each time on input
noCache	Boolean	Prevent caching by appending a timestamp
debounceTime	Number	Debounce time for live server
notFoundMessage	String	Display a no suggestions found message. Leave empty to disable
onRenderItem	RenderCallback	Callback function that returns the label
onSelectItem	ItemCallback	Callback function to call on selection
onClearItem	ValueCallback	Callback function to call on clear
onServerResponse	ServerCallback	Callback function to process server response. Must return a Promise
onServerError	ErrorCallback	Callback function to process server errors.
onChange	ItemCallback	Callback function to call on change-event. Returns currently selected item if any
onBeforeFetch	FetchCallback	Callback function before fetch
onAfterFetch	FetchCallback	Callback function after fetch

Callbacks

RenderCallback ⇒ string

Param	Type
item	Object
label	String
inst	Autocomplete

ItemCallback ⇒ void

Param	Type
item	Object
inst	Autocomplete

ValueCallback ⇒ void

Param	Type
value	String
inst	Autocomplete

ServerCallback ⇒ Promise

Param	Type
response	Response
inst	Autocomplete

ErrorCallback ⇒ void

Param	Type
e	Error
signal	AbortSignal
inst	Autocomplete

Tips

• Use arrow down to show dropdown (and arrow up to hide it)
• If you have a really long list of options, a scrollbar will be used
• Access instance on a given element with Autocomplete.getInstance(myEl)
• Use type="search" for your inputs to get a clear icon

Groups

You can have your items grouped by using the following syntax:

const src = [
  {
    group: "My Group Name",
    items: [
      {
        value: "...",
        label: "...",
      },
    ],
  },
];

Not using Bootstrap ?

This class does NOT depends on Bootstrap JS. If you are not using Bootstrap, you can simply implement the css the way you like it :-)

Demo

https://codepen.io/lekoalabe/pen/MWXydNQ or see demo.html

Custom element

You can now use this as a custom element as part of my Formidable Elements collection.

Browser supports

Modern browsers (edge, chrome, firefox, safari... not IE11). Add a warning if necessary.

Also check out

• Bootstrap 5 Tags: tags input for bootstrap
• BS Companion: the perfect bootstrap companion
• Admini: the minimalistic bootstrap 5 admin panel