apps/mantine.dev/src/pages/core/autocomplete.mdx
import { AutocompleteDemos } from '@docs/demos'; import { Layout } from '@/layout'; import { MDX_DATA } from '@/mdx';
export default Layout(MDX_DATA.Autocomplete);
<ComboboxDisclaimer component="Autocomplete" />Autocomplete is not a searchable select, it is a text input with suggestions.
Values are not enforced to be one of the suggestions – users can type anything.
If you need a searchable select, use the Select component instead.
To learn more about the differences between Autocomplete and Select, check the
help center article.
Autocomplete provides users with a list of suggestions based on the input,
however users are not limited to suggestions and can type anything.
Set loading prop to display a loading indicator. By default, the loader is displayed on the right side of the input.
You can change the position with the loadingPosition prop to 'left' or 'right'. This is useful for async operations like API calls, searches, or validations:
The Autocomplete value must be a string; other types are not supported.
The onChange function is called with a string value as a single argument.
import { useState } from 'react';
import { Autocomplete } from '@mantine/core';
function Demo() {
const [value, setValue] = useState('');
return <Autocomplete data={[]} value={value} onChange={setValue} />;
}
Autocomplete can be used with uncontrolled forms the same way as a native input element.
Set the name attribute to include autocomplete value in FormData object on form submission.
To control the initial value in uncontrolled forms, use the defaultValue prop.
Example usage of uncontrolled Autocomplete with FormData:
import { Autocomplete } from '@mantine/core';
function Demo() {
return (
<form
onSubmit={(event) => {
event.preventDefault();
const formData = new FormData(event.currentTarget);
console.log('Autocomplete value:', formData.get('country'));
}}
>
<Autocomplete
label="Select your country"
placeholder="Pick one"
name="country"
data={['United States', 'Canada', 'Mexico']}
defaultValue="United States"
/>
<button type="submit">Submit</button>
</form>
);
}
Set the selectFirstOptionOnChange prop to automatically select the first option in the dropdown when the input value changes.
This feature allows users to type a value and immediately press Enter to select the first matching option,
without needing to press the arrow down key first.
Set the autoSelectOnBlur prop to automatically select the highlighted option when the input loses focus.
To see this feature in action: select an option with the up/down arrows, then click outside the input:
By default, options are sorted by their position in the data array. You can change this behavior
with the filter function:
You can implement fuzzy search using the fuse.js library to match options even with typos or partial matches:
<Demo data={AutocompleteDemos.fuzzySearch} /> <ComboboxLargeData component="Autocomplete" /> <Demo data={AutocompleteDemos.limit} />The renderOption callback allows you to customize option rendering. It is called with an option object.
The function must return a React node.
The Autocomplete component does not support a nothing found message. It is designed to
accept any string as a value, so it does not make sense to show a nothing found message.
If you want to limit user input to suggestions, you can use a searchable Select
component instead. To learn more about the differences between Autocomplete and Select, check the
help center article.
By default, the options list is wrapped with ScrollArea.Autosize.
You can control the dropdown max-height with the maxDropdownHeight prop if you do not change the default settings.
If you want to use native scrollbars, set withScrollArea={false}. Note that in this case,
you will need to change the dropdown styles with Styles API.
Set floatingHeight="viewport" to make the dropdown grow to fill the available vertical
space in the viewport. The flip middleware is disabled in this mode – the dropdown
always opens in the configured direction and is constrained to the viewport edges instead
of flipping to the other side. Useful when working with large option lists:
When an option is disabled, it cannot be selected and is ignored in keyboard navigation.
<Demo data={AutocompleteDemos.disabledOptions} /> <ComboboxProps component="Autocomplete" />To use Autocomplete inside popover, you need to set withinPortal: false:
Set the clearable prop to display the clear button in the right section. The button is not displayed
when:
You can control the dropdown opened state with the dropdownOpened prop. Additionally,
you can use onDropdownClose and onDropdownOpen to listen to dropdown opened state changes.
By default, the dropdown is displayed below the input if there is enough space; otherwise it is displayed above the input.
You can change this behavior by setting the position and middlewares props, which are passed down to the
underlying Popover component.
Example of dropdown that is always displayed above the input:
<Demo data={AutocompleteDemos.dropdownPosition} />By default, dropdown animations are disabled. To enable them, you can set transitionProps,
which will be passed down to the underlying Transition component.
Set readOnly to make the input read only. When readOnly is set,
Autocomplete will not show suggestions and will not call the onChange function.
Set disabled to disable the input. When disabled is set,
users cannot interact with the input and Autocomplete will not show suggestions.