Autocomplete
Bootstrap 5 Autocomplete component
Autocomplete component predicts the words being typed based on the first few letters given by the user. You can search the list using basic scroll and the keyboard arrows
Note: Read the API tab to find all available options and advanced customization
Basic example
The filter option is required in order for component to work properly. The option
accepts a function that is expected to return an array of results or a
Promise that resolves to an array of results.
<div id="basic" class="form-outline">
<input type="text" id="form11" class="form-control" />
<label class="form-label" for="form1">Example label</label>
</div>
const basicAutocomplete = document.querySelector('#basic');
const data = ['One', 'Two', 'Three', 'Four', 'Five'];
const dataFilter = (value) => {
return data.filter((item) => {
return item.toLowerCase().startsWith(value.toLowerCase());
});
};
new mdb.Autocomplete(basicAutocomplete, {
filter: dataFilter
});
Display value
The displayValue option allow to separate oryginal result value from the value
that will be displayed in the result list or input (after selection). Its useful when the data
returned by the filter function is an array of objects. You can specify which
parameter of the object should be displayed.
<div id="displayValue" class="form-outline">
<input type="text" id="form13" class="form-control" />
<label class="form-label" for="form1">Example label</label>
<div class="autocomplete-custom-content"></div>
</div>
const displayValueAutocomplete = document.querySelector('#displayValue');
const data = [
{ title: 'One', description: 'Lorem ipsum dolor sit, amet consectetur adipisicing elit' },
{ title: 'Two', description: 'Lorem ipsum dolor sit, amet consectetur adipisicing elit' },
{ title: 'Three', description: 'Lorem ipsum dolor sit, amet consectetur adipisicing elit' },
{ title: 'Four', description: 'Lorem ipsum dolor sit, amet consectetur adipisicing elit' },
{ title: 'Five', description: 'Lorem ipsum dolor sit, amet consectetur adipisicing elit' }
];
const dataFilter = (value) => {
return data.filter((item) => {
return item.title.toLowerCase().startsWith(value.toLowerCase());
});
};
new mdb.Autocomplete(displayValueAutocomplete, {
filter: dataFilter,
displayValue: (value) => value.title,
});
Asynchronous search
The function passed to the filter option can return a Promise that
resolves to an array of results. By default the component expects to receive data as an array
of strings. If you want to return an array of objects instead, you can use
displayValue option to specify which parameter should be used as a display value
of the specific result.
<div id="async" class="form-outline autocomplete">
<input type="text" id="form2" class="form-control" />
<label class="form-label" for="form2">Example label</label>
</div>
const asyncAutocomplete = document.querySelector('#async');
const asyncFilter = async (query) => {
const url = `https://swapi.py4e.com/api/people/?search=${encodeURI(query)}`;
const response = await fetch(url);
const data = await response.json();
return data.results;
};
new mdb.Autocomplete(asyncAutocomplete, {
filter: asyncFilter,
displayValue: (value) => value.name
});
Threshold
Use threshold option to specify a minimum number of the characters in the input
field needed to perform a search operation.
<div id="threshold" class="form-outline">
<input type="text" id="form3" class="form-control" placeholder="Type 2 characters to search" />
<label class="form-label" for="form3">Example label</label>
</div>
const thresholdAutocomplete = document.querySelector('#threshold');
const data = ['One', 'Two', 'Three', 'Four', 'Five'];
const dataFilter = (value) => {
return data.filter((item) => {
return item.toLowerCase().startsWith(value.toLowerCase());
});
};
new mdb.Autocomplete(thresholdAutocomplete, {
filter: dataFilter,
threshold: 2
});
Custom item template
The itemContent option allow to display custom HTML in the result list. You can
use the listHeight option to modify the result list height when you want to
display more content in the component dropdown.
<div id="customItem" class="form-outline" data-mdb-list-height="290">
<input type="text" id="form14" class="form-control" />
<label class="form-label" for="form1">Example label</label>
</div>
const customItemAutocomplete = document.querySelector('#customItem');
const data = [
{ title: 'One', subtitle: 'Secondary text' },
{ title: 'Two', subtitle: 'Secondary text' },
{ title: 'Three', subtitle: 'Secondary text' },
{ title: 'Four', subtitle: 'Secondary text' },
{ title: 'Five', subtitle: 'Secondary text' },
{ title: 'Six', subtitle: 'Secondary text' },
];
const dataFilter = (value) => {
return data.filter((item) => {
return item.title.toLowerCase().startsWith(value.toLowerCase());
});
};
new mdb.Autocomplete(customItem, {
filter: dataFilter,
displayValue: (value) => value.title,
itemContent: (result) => {
return `
<div class="autocomplete-custom-item-content">
<div class="autocomplete-custom-item-title">${result.title}</div>
<div class="autocomplete-custom-item-subtitle">${result.subtitle}</div>
</div>
`;
},
});
.autocomplete-custom-item-content {
display: flex;
flex-direction: column;
}
.autocomplete-custom-item-title {
font-weight: 500;
}
.autocomplete-custom-item-subtitle {
font-size: 0.8rem;
}
Custom content
A custom content container with a class .autocomplete-custom-content will be displayed at the end of the autocomplete-custom-item-subtitle dropdown. You can use it to display a number of search results.
<div id="customContent" class="form-outline">
<input type="text" id="form16" class="form-control" />
<label class="form-label" for="form1">Example label</label>
<div class="autocomplete-custom-content"></div>
</div>
const customContentAutocomplete = document.querySelector('#customContent');
const data = ['One', 'Two', 'Three', 'Four', 'Five'];
const dataFilter = (value) => {
return data.filter((item) => {
return item.toLowerCase().startsWith(value.toLowerCase());
});
};
new mdb.Autocomplete(customContent, {
filter: dataFilter,
customContent: `
<div class="autocomplete-custom-content"></div>
`,
});
customContent.addEventListener('update.mdb.autocomplete', (event) => {
const resultsLength = event.results.length;
setTimeout(() => {
customContentContainer = document.querySelector('.autocomplete-custom-content');
customContentContainer.innerHTML = `Search results: ${resultsLength}`;
}, 0);
});
.autocomplete-custom-content {
padding: 6.5px 16px;
}
Validation
The input value is automatically validated to ensure that it is a properly formatted email address.
<form class="needs-validation" novalidate style="width: 22rem;">
<div id="validation" class="form-outline">
<input type="text" id="form6" class="form-control" required />
<label class="form-label" for="form6">Example label</label>
<div class="valid-feedback">Looks good!</div>
<div class="invalid-feedback">Input value is required</div>
</div>
<button type="submit" id="submit" class="btn btn-primary btn-sm mt-3">
Submit
</button>
</form>
const validationAutocomplete = document.querySelector('#validation');
const data = ['One', 'Two', 'Three', 'Four', 'Five'];
const dataFilter = (value) => {
return data.filter((item) => {
return item.toLowerCase().startsWith(value.toLowerCase());
});
};
new mdb.Autocomplete(validationAutocomplete, {
filter: dataFilter
});
Auto select
Set autoSelect option to true to enable selecting on Tab press.
<div id="auto-select" class="form-outline">
<input type="text" id="form1" class="form-control" />
<label class="form-label" for="form1">Example label</label>
</div>
const autoSelectAutocomplete = document.querySelector('#auto-select');
const data = ['One', 'Two', 'Three', 'Four', 'Five'];
const dataFilter = (value) => {
return data.filter((item) => {
return item.toLowerCase().startsWith(value.toLowerCase());
});
};
new mdb.Autocomplete(autoSelectAutocomplete, {
filter: dataFilter,
autoSelect: true
});
Autocomplete - API
Usage
Via JavaScript
const myAutocomplete = new mdb.Autocomplete(document.getElementById('myAutocomplete'), options)
Via jQuery
Note: By default, MDB does not include jQuery and you have to add it to the project on your own.
$(document).ready(() => {
$('.example-class').autocomplete(options);
});
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the
option name to data-mdb-, as in data-mdb-no-results="".
| Name | Type | Default | Description |
|---|---|---|---|
autoSelect
|
Boolean | false |
Enables auto selecting on Tab press |
container |
String | 'body' |
Allows to set the parent element for the autocomplete. |
customContent
|
String | '' |
Custom HTML template that will be displayed at the end of the component dropdown |
debounce
|
Number | 300 |
Delay between search queries in milliseconds, improves the component performance |
displayValue
|
Function | (value) => value |
Function executed for complex search results, to get value to display in the results list |
filter |
Function | - |
Function that returns filtered data to the component |
itemContent
|
Function | - |
Function that returns custom template for result item |
listHeight
|
Number | 190 |
Height of the result list |
noResults
|
Function | 'No results found' |
Message that will be displayed in the component dropdown if no result is found |
threshold
|
Number | 0 |
Minimum input length to start search query |
Methods
| Name | Description | Example |
|---|---|---|
open |
Manually opens a component dropdown |
myAutocomplete.open()
|
close |
Manually closes a component dropdown |
myAutocomplete.close()
|
dispose
|
Disposes an autocomplete instance |
myAutocomplete.dispose()
|
getInstance
|
Static method which allows you to get the autocomplete instance associated to a DOM element. |
Autocomplete.getInstance(myAutocomplete)
|
getOrCreateInstance
|
Static method which returns the autocomplete instance associated to a DOM element or create a new one in case it wasn't initialized. |
Autocomplete.getOrCreateInstance(myAutocomplete)
|
initSearch(value)
|
Initialize search results for a specific value |
myAutocomplete.initSearch('')
|
const myAutocomplete = document.getElementById('myAutocomplete')
const autocomplete = new mdb.Autocomplete(myAutocomplete)
autocomplete.open()
Events
| Name | Description |
|---|---|
open.mdb.autocomplete
|
This event fires immediately when the autocomplete dropdown is opened. |
close.mdb.autocomplete
|
This event fires immediately when the autocomplete dropdown is closed. |
itemSelect.mdb.autocomplete
|
This event fires immediately when the autocomplete item is selected. |
update.mdb.autocomplete
|
This event fires immediately when the autocomplete results list is updated. |
const myAutocomplete = document.getElementById('myAutocomplete')
myAutocomplete.addEventListener('open.mdb.autocomplete', (e) => {
// do something...
})
Import
MDB UI KIT also works with module bundlers. Use the following code to import this component:
import { Autocomplete } from 'mdb-ui-kit';
CSS variables
--#{$prefix}autocomplete-label-max-width: #{$autocomplete-label-max-width};
--#{$prefix}autocomplete-label-active-transform: #{$autocomplete-label-active-transform};
--#{$prefix}autocomplete-label-color: #{$autocomplete-label-color};
--#{$prefix}form-outline-select-notch-border-color: #{$form-outline-select-notch-border-color};
--#{$prefix}autocomplete-input-focused-color: #{$autocomplete-input-focused-color};
--#{$prefix}autocomplete-dropdown-container-zindex: #{$autocomplete-dropdown-container-zindex};
--#{$prefix}autocomplete-dropdown-background-color: #{$autocomplete-dropdown-background-color};
--#{$prefix}autocomplete-dropdown-box-shadow: #{$autocomplete-dropdown-box-shadow};
--#{$prefix}autocomplete-dropdown-margin: #{$autocomplete-dropdown-margin};
--#{$prefix}autocomplete-dropdown-transform: #{$autocomplete-dropdown-transform};
--#{$prefix}autocomplete-dropdown-transition: #{$autocomplete-dropdown-transition};
--#{$prefix}autocomplete-dropdown-open-transform: #{$autocomplete-dropdown-open-transform};
--#{$prefix}autocomplete-item-color: #{$autocomplete-item-color};
--#{$prefix}autocomplete-item-padding: #{$autocomplete-item-padding};
--#{$prefix}autocomplete-item-font-size: #{$autocomplete-item-font-size};
--#{$prefix}autocomplete-item-font-weight: #{$autocomplete-item-font-weight};
--#{$prefix}autocomplete-item-hover-background-color: #{$autocomplete-item-hover-background-color};
--#{$prefix}autocomplete-item-disabled-color: #{$autocomplete-item-disabled-color};
SCSS variables
$autocomplete-dropdown-container-zindex: 1065;
$autocomplete-label-max-width: 80%;
$autocomplete-label-active-transform: translateY(-1rem) translateY(0.1rem) scale(0.8);
$autocomplete-input-focused-color: #616161;
$autocomplete-label-color: $primary;
$autocomplete-dropdown-background-color: #fff;
$autocomplete-dropdown-box-shadow: 0 2px 5px 0 rgba(0, 0, 0, 0.16), 0 2px 10px 0 rgba(0, 0, 0, 0.12);
$autocomplete-dropdown-margin: 0;
$autocomplete-dropdown-transform: scaleY(0.8);
$autocomplete-dropdown-transition: all 0.2s;
$autocomplete-dropdown-open-transform: scaleY(1);
$autocomplete-item-color: rgba(0, 0, 0, 0.87);
$autocomplete-item-padding: 6.5px 16px;
$autocomplete-item-font-size: 1rem;
$autocomplete-item-font-weight: 400;
$autocomplete-item-hover-background-color: #ddd;
$autocomplete-item-disabled-color: #9e9e9e;