AutoComplete

Autocomplete function of input field.

When To Use

When you need an input box instead of a selector.
When you need input suggestions or helping text.

The differences with Select are:

AutoComplete is an input box with text hints, and users can type freely. The keyword is aiding input.
Select is selecting among given choices. The keyword is select.

Examples

Basic Usage

Basic Usage, set data source of autocomplete with options property.

TypeScript
JavaScript
import React, { useState } from 'react';
import { AutoComplete } from 'antd';

const mockVal = (str: string, repeat = 1) => ({
  value: str.repeat(repeat),
});

const App: React.FC = () => {
  const [value, setValue] = useState('');
  const [options, setOptions] = useState<{ value: string }[]>([]);

  const onSearch = (searchText: string) => {
    setOptions(
      !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)],
    );
  };

  const onSelect = (data: string) => {
    console.log('onSelect', data);
  };

  const onChange = (data: string) => {
    setValue(data);
  };

  return (
    <>
      <AutoComplete
        options={options}
        style={{ width: 200 }}
        onSelect={onSelect}
        onSearch={onSearch}
        placeholder="input here"
      />
      <br />
      <br />
      <AutoComplete
        value={value}
        options={options}
        style={{ width: 200 }}
        onSelect={onSelect}
        onSearch={onSearch}
        onChange={onChange}
        placeholder="control mode"
      />
    </>
  );
};

export default App;

Customize Input Component

TypeScript
JavaScript
import React, { useState } from 'react';
import { AutoComplete, Input } from 'antd';

const { TextArea } = Input;

const App: React.FC = () => {
  const [options, setOptions] = useState<{ value: string }[]>([]);

  const handleSearch = (value: string) => {
    setOptions(
      !value ? [] : [{ value }, { value: value + value }, { value: value + value + value }],
    );
  };

  const handleKeyPress = (ev: React.KeyboardEvent<HTMLTextAreaElement>) => {
    console.log('handleKeyPress', ev);
  };

  const onSelect = (value: string) => {
    console.log('onSelect', value);
  };

  return (
    <AutoComplete
      options={options}
      style={{ width: 200 }}
      onSelect={onSelect}
      onSearch={handleSearch}
    >
      <TextArea
        placeholder="input here"
        className="custom"
        style={{ height: 50 }}
        onKeyPress={handleKeyPress}
      />
    </AutoComplete>
  );
};

export default App;

Lookup-Patterns - Certain Category

Demonstration of Lookup Patterns: Certain Category. Basic Usage, set options of autocomplete with options property.

TypeScript
JavaScript
import React from 'react';
import { UserOutlined } from '@ant-design/icons';
import { AutoComplete, Input } from 'antd';

const renderTitle = (title: string) => (
  <span>
    {title}
    <a
      style={{ float: 'right' }}
      href="https://www.google.com/search?q=antd"
      target="_blank"
      rel="noopener noreferrer"
    >
      more
    </a>
  </span>
);

const renderItem = (title: string, count: number) => ({
  value: title,
  label: (
    <div
      style={{
        display: 'flex',
        justifyContent: 'space-between',
      }}
    >
      {title}
      <span>
        <UserOutlined /> {count}
      </span>
    </div>
  ),
});

const options = [
  {
    label: renderTitle('Libraries'),
    options: [renderItem('AntDesign', 10000), renderItem('AntDesign UI', 10600)],
  },
  {
    label: renderTitle('Solutions'),
    options: [renderItem('AntDesign UI FAQ', 60100), renderItem('AntDesign FAQ', 30010)],
  },
  {
    label: renderTitle('Articles'),
    options: [renderItem('AntDesign design language', 100000)],
  },
];

const App: React.FC = () => (
  <AutoComplete
    popupClassName="certain-category-search-dropdown"
    dropdownMatchSelectWidth={500}
    style={{ width: 250 }}
    options={options}
  >
    <Input.Search size="large" placeholder="input here" />
  </AutoComplete>
);

export default App;
.certain-category-search-dropdown .ant-select-dropdown-menu-item-group-title {
  color: #666;
  font-weight: bold;
}

.certain-category-search-dropdown .ant-select-dropdown-menu-item-group {
  border-bottom: 1px solid #f6f6f6;
}

.certain-category-search-dropdown .ant-select-dropdown-menu-item {
  padding-left: 16px;
}

.certain-category-search-dropdown .ant-select-dropdown-menu-item.show-all {
  text-align: center;
  cursor: default;
}

.certain-category-search-dropdown .ant-select-dropdown-menu {
  max-height: 300px;
}

Status

Add status to AutoComplete with status, which could be error or warning.

TypeScript
JavaScript
import React, { useState } from 'react';
import { AutoComplete, Space } from 'antd';

const mockVal = (str: string, repeat = 1) => ({
  value: str.repeat(repeat),
});

const App: React.FC = () => {
  const [options, setOptions] = useState<{ value: string }[]>([]);

  const onSearch = (searchText: string) => {
    setOptions(
      !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)],
    );
  };

  return (
    <Space direction="vertical" style={{ width: '100%' }}>
      <AutoComplete options={options} onSearch={onSearch} status="error" style={{ width: 200 }} />
      <AutoComplete options={options} onSearch={onSearch} status="warning" style={{ width: 200 }} />
    </Space>
  );
};

export default App;

Customized

You could set custom Option label

TypeScript
JavaScript
import React, { useState } from 'react';
import { AutoComplete } from 'antd';

const App: React.FC = () => {
  const [options, setOptions] = useState<{ value: string; label: string }[]>([]);

  const handleSearch = (value: string) => {
    let res: { value: string; label: string }[] = [];
    if (!value || value.indexOf('@') >= 0) {
      res = [];
    } else {
      res = ['gmail.com', '163.com', 'qq.com'].map((domain) => ({
        value,
        label: `${value}@${domain}`,
      }));
    }
    setOptions(res);
  };

  return (
    <AutoComplete
      style={{ width: 200 }}
      onSearch={handleSearch}
      placeholder="input here"
      options={options}
    />
  );
};

export default App;

Non-case-sensitive AutoComplete

A non-case-sensitive AutoComplete

TypeScript
JavaScript
import React from 'react';
import { AutoComplete } from 'antd';

const options = [
  { value: 'Burns Bay Road' },
  { value: 'Downing Street' },
  { value: 'Wall Street' },
];

const App: React.FC = () => (
  <AutoComplete
    style={{ width: 200 }}
    options={options}
    placeholder="try to type `b`"
    filterOption={(inputValue, option) =>
      option!.value.toUpperCase().indexOf(inputValue.toUpperCase()) !== -1
    }
  />
);

export default App;

Lookup-Patterns - Uncertain Category

Demonstration of Lookup Patterns: Uncertain Category.

TypeScript
JavaScript
import React, { useState } from 'react';
import { AutoComplete, Input } from 'antd';
import type { SelectProps } from 'antd/es/select';

const getRandomInt = (max: number, min = 0) => Math.floor(Math.random() * (max - min + 1)) + min;

const searchResult = (query: string) =>
  new Array(getRandomInt(5))
    .join('.')
    .split('.')
    .map((_, idx) => {
      const category = `${query}${idx}`;
      return {
        value: category,
        label: (
          <div
            style={{
              display: 'flex',
              justifyContent: 'space-between',
            }}
          >
            <span>
              Found {query} on{' '}
              <a
                href={`https://s.taobao.com/search?q=${query}`}
                target="_blank"
                rel="noopener noreferrer"
              >
                {category}
              </a>
            </span>
            <span>{getRandomInt(200, 100)} results</span>
          </div>
        ),
      };
    });

const App: React.FC = () => {
  const [options, setOptions] = useState<SelectProps<object>['options']>([]);

  const handleSearch = (value: string) => {
    setOptions(value ? searchResult(value) : []);
  };

  const onSelect = (value: string) => {
    console.log('onSelect', value);
  };

  return (
    <AutoComplete
      dropdownMatchSelectWidth={252}
      style={{ width: 300 }}
      options={options}
      onSelect={onSelect}
      onSearch={handleSearch}
    >
      <Input.Search size="large" placeholder="input here" enterButton />
    </AutoComplete>
  );
};

export default App;

API

Property	Description	Type	Default	Version
allowClear	Show clear button	boolean	false
autoFocus	If get focus when component mounted	boolean	false
backfill	If backfill selected item the input when using keyboard	boolean	false
children (for customize input element)	Customize input element	HTMLInputElement \| HTMLTextAreaElement \| React.ReactElement<InputProps>	<Input />
children (for dataSource)	Data source to auto complete	React.ReactElement<OptionProps> \| Array<React.ReactElement<OptionProps>>	-
defaultActiveFirstOption	Whether active first option by default	boolean	true
defaultOpen	Initial open state of dropdown	boolean	-
defaultValue	Initial selected option	string	-
disabled	Whether disabled select	boolean	false
popupClassName	The className of dropdown menu	string	-	4.23.0
dropdownMatchSelectWidth	Determine whether the dropdown menu and the select input are the same width. Default set `min-width` same as input. Will ignore when value less than select width. `false` will disable virtual scroll	boolean \| number	true
filterOption	If true, filter options by input, if function, filter options against it. The function will receive two arguments, `inputValue` and `option`, if the function returns true, the option will be included in the filtered set; Otherwise, it will be excluded	boolean \| function(inputValue, option)	true
notFoundContent	Specify content to show when no result matches	string	`Not Found`
open	Controlled open state of dropdown	boolean	-
options	Select options. Will get better perf than jsx definition	{ label, value }[]	-
placeholder	The placeholder of input	string	-
status	Set validation status	'error' \| 'warning'	-	4.19.0
value	Selected option	string	-
onBlur	Called when leaving the component	function()	-
onChange	Called when selecting an option or changing an input value	function(value)	-
onDropdownVisibleChange	Call when dropdown open	function(open)	-
onFocus	Called when entering the component	function()	-
onSearch	Called when searching items	function(value)	-
onSelect	Called when a option is selected. param is option's value and option instance	function(value, option)	-
onClear	Called when clear	function	-	4.6.0

Methods

Name	Description	Version
blur()	Remove focus
focus()	Get focus

FAQ

Why doesn't the text composition system work well with onSearch in controlled mode?

Please use onChange to manage control state. onSearch is used for searching input which is not the same as onChange. Besides, clicking on the option will not trigger the onSearch event.

Related issue: #18230 #17916

import React, { useState } from 'react'; import { AutoComplete } from 'antd'; const mockVal = (str: string, repeat = 1) => ({ value: str.repeat(repeat), }); const App: React.FC = () => { const [value, setValue] = useState(''); const [options, setOptions] = useState<{ value: string }[]>([]); const onSearch = (searchText: string) => { setOptions( !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)], ); }; const onSelect = (data: string) => { console.log('onSelect', data); }; const onChange = (data: string) => { setValue(data); }; return ( <> <AutoComplete options={options} style={{ width: 200 }} onSelect={onSelect} onSearch={onSearch} placeholder="input here" /> <br /> <br /> <AutoComplete value={value} options={options} style={{ width: 200 }} onSelect={onSelect} onSearch={onSearch} onChange={onChange} placeholder="control mode" /> </> ); }; export default App;

import React, { useState } from 'react'; import { AutoComplete, Input } from 'antd'; const { TextArea } = Input; const App: React.FC = () => { const [options, setOptions] = useState<{ value: string }[]>([]); const handleSearch = (value: string) => { setOptions( !value ? [] : [{ value }, { value: value + value }, { value: value + value + value }], ); }; const handleKeyPress = (ev: React.KeyboardEvent<HTMLTextAreaElement>) => { console.log('handleKeyPress', ev); }; const onSelect = (value: string) => { console.log('onSelect', value); }; return ( <AutoComplete options={options} style={{ width: 200 }} onSelect={onSelect} onSearch={handleSearch} > <TextArea placeholder="input here" className="custom" style={{ height: 50 }} onKeyPress={handleKeyPress} /> </AutoComplete> ); }; export default App;

import React from 'react'; import { UserOutlined } from '@ant-design/icons'; import { AutoComplete, Input } from 'antd'; const renderTitle = (title: string) => ( <span> {title} <a style={{ float: 'right' }} href="https://www.google.com/search?q=antd" target="_blank" rel="noopener noreferrer" > more </a> </span> ); const renderItem = (title: string, count: number) => ({ value: title, label: ( <div style={{ display: 'flex', justifyContent: 'space-between', }} > {title} <span> <UserOutlined /> {count} </span> </div> ), }); const options = [ { label: renderTitle('Libraries'), options: [renderItem('AntDesign', 10000), renderItem('AntDesign UI', 10600)], }, { label: renderTitle('Solutions'), options: [renderItem('AntDesign UI FAQ', 60100), renderItem('AntDesign FAQ', 30010)], }, { label: renderTitle('Articles'), options: [renderItem('AntDesign design language', 100000)], }, ]; const App: React.FC = () => ( <AutoComplete popupClassName="certain-category-search-dropdown" dropdownMatchSelectWidth={500} style={{ width: 250 }} options={options} > <Input.Search size="large" placeholder="input here" /> </AutoComplete> ); export default App;

.certain-category-search-dropdown .ant-select-dropdown-menu-item-group-title { color: #666; font-weight: bold; } .certain-category-search-dropdown .ant-select-dropdown-menu-item-group { border-bottom: 1px solid #f6f6f6; } .certain-category-search-dropdown .ant-select-dropdown-menu-item { padding-left: 16px; } .certain-category-search-dropdown .ant-select-dropdown-menu-item.show-all { text-align: center; cursor: default; } .certain-category-search-dropdown .ant-select-dropdown-menu { max-height: 300px; }

import React, { useState } from 'react'; import { AutoComplete, Space } from 'antd'; const mockVal = (str: string, repeat = 1) => ({ value: str.repeat(repeat), }); const App: React.FC = () => { const [options, setOptions] = useState<{ value: string }[]>([]); const onSearch = (searchText: string) => { setOptions( !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)], ); }; return ( <Space direction="vertical" style={{ width: '100%' }}> <AutoComplete options={options} onSearch={onSearch} status="error" style={{ width: 200 }} /> <AutoComplete options={options} onSearch={onSearch} status="warning" style={{ width: 200 }} /> </Space> ); }; export default App;

import React, { useState } from 'react'; import { AutoComplete } from 'antd'; const App: React.FC = () => { const [options, setOptions] = useState<{ value: string; label: string }[]>([]); const handleSearch = (value: string) => { let res: { value: string; label: string }[] = []; if (!value || value.indexOf('@') >= 0) { res = []; } else { res = ['gmail.com', '163.com', 'qq.com'].map((domain) => ({ value, label: `${value}@${domain}`, })); } setOptions(res); }; return ( <AutoComplete style={{ width: 200 }} onSearch={handleSearch} placeholder="input here" options={options} /> ); }; export default App;

import React from 'react'; import { AutoComplete } from 'antd'; const options = [ { value: 'Burns Bay Road' }, { value: 'Downing Street' }, { value: 'Wall Street' }, ]; const App: React.FC = () => ( <AutoComplete style={{ width: 200 }} options={options} placeholder="try to type `b`" filterOption={(inputValue, option) => option!.value.toUpperCase().indexOf(inputValue.toUpperCase()) !== -1 } /> ); export default App;

import React, { useState } from 'react'; import { AutoComplete, Input } from 'antd'; import type { SelectProps } from 'antd/es/select'; const getRandomInt = (max: number, min = 0) => Math.floor(Math.random() * (max - min + 1)) + min; const searchResult = (query: string) => new Array(getRandomInt(5)) .join('.') .split('.') .map((_, idx) => { const category = `${query}${idx}`; return { value: category, label: ( <div style={{ display: 'flex', justifyContent: 'space-between', }} > <span> Found {query} on{' '} <a href={`https://s.taobao.com/search?q=${query}`} target="_blank" rel="noopener noreferrer" > {category} </a> </span> <span>{getRandomInt(200, 100)} results</span> </div> ), }; }); const App: React.FC = () => { const [options, setOptions] = useState<SelectProps<object>['options']>([]); const handleSearch = (value: string) => { setOptions(value ? searchResult(value) : []); }; const onSelect = (value: string) => { console.log('onSelect', value); }; return ( <AutoComplete dropdownMatchSelectWidth={252} style={{ width: 300 }} options={options} onSelect={onSelect} onSearch={handleSearch} > <Input.Search size="large" placeholder="input here" enterButton /> </AutoComplete> ); }; export default App;

API

Property	Description	Type	Default	Version
allowClear	Show clear button	boolean	false
autoFocus	If get focus when component mounted	boolean	false
backfill	If backfill selected item the input when using keyboard	boolean	false
children (for customize input element)	Customize input element	HTMLInputElement \| HTMLTextAreaElement \| React.ReactElement<InputProps>	<Input />
children (for dataSource)	Data source to auto complete	React.ReactElement<OptionProps> \| Array<React.ReactElement<OptionProps>>	-
defaultActiveFirstOption	Whether active first option by default	boolean	true
defaultOpen	Initial open state of dropdown	boolean	-
defaultValue	Initial selected option	string	-
disabled	Whether disabled select	boolean	false
popupClassName	The className of dropdown menu	string	-	4.23.0
dropdownMatchSelectWidth	Determine whether the dropdown menu and the select input are the same width. Default set `min-width` same as input. Will ignore when value less than select width. `false` will disable virtual scroll	boolean \| number	true
filterOption	If true, filter options by input, if function, filter options against it. The function will receive two arguments, `inputValue` and `option`, if the function returns true, the option will be included in the filtered set; Otherwise, it will be excluded	boolean \| function(inputValue, option)	true
notFoundContent	Specify content to show when no result matches	string	`Not Found`
open	Controlled open state of dropdown	boolean	-
options	Select options. Will get better perf than jsx definition	{ label, value }[]	-
placeholder	The placeholder of input	string	-
status	Set validation status	'error' \| 'warning'	-	4.19.0
value	Selected option	string	-
onBlur	Called when leaving the component	function()	-
onChange	Called when selecting an option or changing an input value	function(value)	-
onDropdownVisibleChange	Call when dropdown open	function(open)	-
onFocus	Called when entering the component	function()	-
onSearch	Called when searching items	function(value)	-
onSelect	Called when a option is selected. param is option's value and option instance	function(value, option)	-
onClear	Called when clear	function	-	4.6.0

Name

Description

Version

blur()

Remove focus

focus()

Get focus

Ant Design

AutoComplete

Ant Design

AutoComplete

When To Use

Examples

API

Methods

FAQ

Why doesn't the text composition system work well with onSearch in controlled mode?

When To Use

Examples

API

Methods

FAQ

Why doesn't the text composition system work well with onSearch in controlled mode?