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

Required ES init: Autocomplete *
* UMD autoinits are enabled by default. This means that you don't need to initialize the component manually. However if you are using MDBootstrap ES format then you should pass the required components to the initMDB method.

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.

Edit in sandbox 
<div id="basic" class="form-outline" data-mdb-input-init>
  <input type="text" id="form11" class="form-control" />
  <label class="form-label" for="form1">Example label</label>
</div>
// Initialization for ES Users
import { Input, Autocomplete, initMDB } from "mdb-ui-kit";

initMDB({ Input });

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 Autocomplete(basicAutocomplete, {
  filter: dataFilter
});
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.

Edit in sandbox 
<div id="displayValue" class="form-outline" data-mdb-input-init>
  <input type="text" id="form13" class="form-control" />
  <label class="form-label" for="form1">Example label</label>
</div>
// Initialization for ES Users
import { Input, Autocomplete, initMDB } from "mdb-ui-kit";

initMDB({ Input });

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 Autocomplete(displayValueAutocomplete, {
  filter: dataFilter,
  displayValue: (value) => value.title,
});
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,
});

Threshold

Use threshold option to specify a minimum number of the characters in the input field needed to perform a search operation.

Edit in sandbox 
<div id="threshold" class="form-outline" data-mdb-input-init>
  <input type="text" id="form3" class="form-control" placeholder="Type 2 characters to search" />
  <label class="form-label" for="form3">Example label</label>
</div>
// Initialization for ES Users
import { Input, Autocomplete, initMDB } from "mdb-ui-kit";

initMDB({ Input });

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 Autocomplete(thresholdAutocomplete, {
  filter: dataFilter,
  threshold: 2
});
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.

Edit in sandbox 
<div id="customItem" class="form-outline" data-mdb-input-init data-mdb-list-height="290">
  <input type="text" id="form14" class="form-control" />
  <label class="form-label" for="form1">Example label</label>
</div>
// Initialization for ES Users
import { Input, Autocomplete, initMDB } from "mdb-ui-kit";

initMDB({ Input });

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 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>
    `;
  },
});
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 dropdown. You can use it to display a number of search results.

Edit in sandbox 
<div id="customContent" class="form-outline" data-mdb-input-init>
  <input type="text" id="form16" class="form-control" />
  <label class="form-label" for="form1">Example label</label>
</div>
// Initialization for ES Users
import { Input, Autocomplete, initMDB } from "mdb-ui-kit";

initMDB({ Input });

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 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);
});
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.

Looks good!
Input value is required
Edit in sandbox 
<form class="needs-validation" novalidate style="width: 22rem;">
  <div id="validation" class="form-outline" data-mdb-input-init>
    <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>
// Initialization for ES Users
import { Input, Autocomplete, initMDB } from "mdb-ui-kit";

initMDB({ Input });

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 Autocomplete(validationAutocomplete, {
  filter: dataFilter
});
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.

Edit in sandbox 
<div id="auto-select" class="form-outline" data-mdb-input-init>
  <input type="text" id="form1" class="form-control" />
  <label class="form-label" for="form1">Example label</label>
</div>
// Initialization for ES Users
import { Input, Autocomplete, initMDB } from "mdb-ui-kit";

initMDB({ Input });

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 Autocomplete(autoSelectAutocomplete, {
  filter: dataFilter,
  autoSelect: true
});
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

Import

Importing components depends on how your application works. If you intend to use the MDBootstrap ES format, you must first import the component and then initialize it with the initMDB method. If you are going to use the UMD format, just import the mdb-ui-kit package.

Edit in sandbox 
import { Autocomplete, initMDB } from "mdb-ui-kit";
initMDB({ Autocomplete });
import "mdb-ui-kit"

Usage

Via JavaScript

Edit in sandbox 
const myAutocomplete = new Autocomplete(document.getElementById('myAutocomplete'), options)
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.

Edit in sandbox 
$(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-container="body".

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 | null (value) => value Function executed for complex search results, to get value to display in the results list
filter Function null Function that returns filtered data to the component
itemContent Function | null null Function that returns custom template for result item
listHeight Number 190 Height of the result list
noResults String '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)
search Initialize search results for a specific value myAutocomplete.search('')
Edit in sandbox 
const myAutocomplete = document.getElementById('myAutocomplete');
const autocomplete = new Autocomplete(myAutocomplete);
autocomplete.open();
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.
Edit in sandbox 
const myAutocomplete = document.getElementById('myAutocomplete')
myAutocomplete.addEventListener('open.mdb.autocomplete', (e) => {
  // do something...
})

CSS variables

Edit in sandbox 
// .autocomplete-label
--#{$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};

// .form-outline
--#{$prefix}form-outline-select-notch-border-color: #{$form-outline-select-notch-border-color};

// .autocomplete-input.focused
--#{$prefix}autocomplete-input-focused-color: #{$autocomplete-input-focused-color};

// .autocomplete-dropdown-container
--#{$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};
--#{$prefix}autocomplete-scrollbar-thumb-background-color: #{$autocomplete-scrollbar-thumb-background-color};

SCSS variables

Edit in sandbox 
$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: var(--#{$prefix}surface-color);
$autocomplete-label-color: $primary;
$autocomplete-dropdown-background-color: var(--#{$prefix}surface-bg);
$autocomplete-dropdown-box-shadow: 0 2px 5px 0 rgba(var(--#{$prefix}box-shadow-color-rgb), 0.16), 0 2px 10px 0 rgba(var(--#{$prefix}box-shadow-color-rgb), 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: var(--#{$prefix}surface-color);
$autocomplete-item-padding: 6.5px 16px;
$autocomplete-item-font-size: 1rem;
$autocomplete-item-font-weight: 400;
$autocomplete-item-hover-background-color: var(--#{$prefix}highlight-bg-color);
$autocomplete-item-disabled-color: rgba(var(--#{$prefix}surface-color-rgb), 0.5);
$autocomplete-scrollbar-thumb-background-color: var(--#{$prefix}scrollbar-thumb-bg);