Autocomplete

React 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 dataFilter property 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.

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';

const defaultData = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight'];

export default function App() {
  const [data, setData] = useState(defaultData);

  const onSearch = (value: string) =>
    setData(defaultData.filter((item) => item.toLowerCase().startsWith(value.toLowerCase())));

  return (
    <MDBAutocomplete data={data} label='Example label' onSearch={onSearch} />
  );
}

Controlled value

The value property allows to control the value of the input. Add a handler to the onChange event to update the outer state.

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';

const defaultData = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight'];

export default function App() {
  const [data, setData] = useState(defaultData);
  const [value, setValue] = useState('');

  const onSearch = (value: string) =>
    setData(defaultData.filter((item) => item.toLowerCase().startsWith(value.toLowerCase())));

  return (
    <MDBAutocomplete
      data={data}
      label='Example label'
      onSearch={onSearch}
      value={value}
      onChange={(value) => setValue(value)}
    />
  );
}

Controlled open state

The open property allows to control the visibility of the result list.

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';

const defaultData = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight'];

export default function App() {
  const [open, setOpen] = useState(false);
  const [data, setData] = useState(defaultData);

  const onSearch = (value: string) =>
    setData(defaultData.filter((item) => item.toLowerCase().startsWith(value.toLowerCase())));

  const handleOpen = () => setOpen(true);
  const handleClose = () => setOpen(false);

  return (
    <MDBAutocomplete
      data={data}
      label='Example label'
      onSearch={onSearch}
      open={open}
      onOpen={handleOpen}
      onClose={handleClose}
    />
  );
}

Display value

The displayValue property 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 dataFilter function is an array of objects. You can specify which parameter of the object should be displayed.

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';

const defaultAdvanced = [
  { 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' },
];

export default function App() {
  const [advancedData, setAdvancedData] = useState(defaultAdvanced);

  const onAdvancedSearch = (value: string) =>
    setAdvancedData(defaultAdvanced.filter((item) => item.title.toLowerCase().startsWith(value.toLowerCase())));

  return (
    <MDBAutocomplete
      data={advancedData}
      label='Example label'
      displayValue={(row) => row.title}
      onSearch={onAdvancedSearch}
    />
  );
}

Asynchronous search

The function passed to the dataFilter property 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 property to specify which parameter should be used as a display value of the specific result.

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';

export default function App() {
  const [isLoading, setIsLoading] = useState(false);
  const [asyncData, setAsyncData] = useState([]);

  const onAsyncSearch = async (query: string) => {
    const url = `https://swapi.py4e.com/api/people/?search=${encodeURI(query)}`;

    setIsLoading(true);

    const response = await fetch(url);
    const data = await response.json();

    await setIsLoading(false);

    setAsyncData(data.results);
  };

  return (
    <MDBAutocomplete
      data={asyncData}
      isLoading={isLoading}
      label='Example label'
      displayValue={(row) => row.name}
      onSearch={onAsyncSearch}
    />
  );
}

Threshold

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

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';

const defaultData = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight'];

export default function App() {
  const [thresholdData, setThresholdData] = useState(defaultData);

  const onThresholdSearch = (value: string) =>
  value.length > 1
    ? setThresholdData(defaultData.filter((item) => item.toLowerCase().startsWith(value.toLowerCase())))
    : setThresholdData([]);

  return (
    <MDBAutocomplete data={thresholdData} label='Example label' onSearch={onThresholdSearch} />
  );
}

Custom item template

The itemContent property allow to display custom HTML in the result list.

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';

const customDefData = [
  { 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' },
];

export default function App() {
  const [customData, setCustomData] = useState(customDefData);

  const onCustomSearch = (value: string) =>
    setCustomData(customDefData.filter((item) => item.title.toLowerCase().startsWith(value.toLowerCase())));

  return (
    <MDBAutocomplete
      data={customData}
      label='Example label'
      displayValue={(row) => row.title}
      onSearch={onCustomSearch}
      itemContent={(result) => (
        <div className='autocomplete-custom-item-content'>
          <div className='autocomplete-custom-item-title'>{result.title}</div>
          <div className='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.

Example label

Show code

import React, { useState } from 'react';
import { MDBAutocomplete } from 'mdb-react-ui-kit';


const defaultData = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight'];

export default function App() {
  const [contentData, setContentData] = useState(defaultData);

  const onContentSearch = (value: string) =>
    setContentData(defaultData.filter((item) => item.toLowerCase().startsWith(value.toLowerCase())));

  return (
    <MDBAutocomplete
      data={contentData}
      label='Example label'
      onSearch={onContentSearch}
      customContent={<div className='autocomplete-custom-content'>Search results: {contentData.length}</div>}
    />
  );
}

.autocomplete-custom-content {
  padding: 6.5px 16px;
}

Validation

Show code

import React, { useState } from 'react';
import { MDBAutocomplete, MDBValidation, MDBValidationItem, MDBBtn } from 'mdb-react-ui-kit';

const defaultData = ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight'];

export default function App() {
  const [data, setData] = useState(defaultData);

  const onSearch = (value: string) =>
    setData(defaultData.filter((item) => item.toLowerCase().startsWith(value.toLowerCase())));

  return (
    <MDBValidation>
      <MDBValidationItem>
         <MDBAutocomplete data={data} label='Example label' onSearch={onSearch} />
      </MDBValidationItem>

      <MDBBtn size='sm' className='mt-3' type='submit'>
        Submit
      </MDBBtn>
    </MDBValidation>
  );
}

Autocomplete - API

Import

Show code

import { MDBAutocomplete } from 'mdb-react-ui-kit';

Properties

MDBAutocomplete

Name	Type	Default	Description	Example
`autoSelect`	boolean	`false`	Enables auto selecting on Tab press	`<MDBAutocomplete autoSelect />`
`customContent`	ReactNode	`-`	Custom HTML template that will be displayed at the end of the component dropdown	`<MDBAutocomplete customContent={element} />`
`data`	string[] \| Record[]	`[]`	Autocomplete data state	`<MDBAutocomplete data={defaultData} />`
`listHeight`	string	`'190px'`	The autcomplete list height	`<MDBAutocomplete listHeight="200px" />`
`isLoading`	boolean	`false`	Enables input spinner	`<MDBAutocomplete isLoading={isLoading} />`
`open`	boolean	`-`	Enables controlling the open state	`<MDBAutocomplete open={true} />`
`noResults`	string	`'No results found'`	Text displayed with no matching results	`<MDBAutocomplete noResults='-' />`
`ref`	React.Ref	`undefined`	Reference to the input element	`<MDBInput ref={inputReference} />`

Events

Name	Type	Description
`displayValue`	(row: Record) => any	Function executed for complex search results, to get value to display in the results list
`itemContent`	(value: Record) => ReactNode	Function that returns custom template for result item
`onClose`	() => void	Callback fired when the component requests to be closed
`onClosed`	() => void	Executed when closing transition is over
`onOpen`	() => void	Callback fired when the component requests to be opened
`onOpened`	() => void	Executed when opening transition is over
`onSelect`	(itemData: string \| Record) => void	Executed when option selected
`onSearch`	(data: string) => void	Executed when the autocomplete value changes

CSS variables

Show code

--#{$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

Show code

SCSS

$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;

Autocomplete

React Bootstrap 5 Autocomplete component

Basic example

Controlled value

Controlled open state

Display value

Asynchronous search

Threshold

Custom item template

Custom content

Validation

Related resources

Autocomplete - API

Import

Properties

MDBAutocomplete

Events

CSS variables

SCSS variables