Ant Design

⌘ K

5.25.3

AutoComplete

Autocomplete function of input field.

Importimport { AutoComplete } from "antd";

Sourcecomponents/auto-complete

Docs

Edit this page Changelog

Ant Design

⌘ K

5.25.3

AutoComplete

Autocomplete function of input field.

Importimport { AutoComplete } from "antd";

Sourcecomponents/auto-complete

Docs

Edit this page Changelog

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

API

Common props ref：Common props

Property	Description	Type	Default	Version
allowClear	Show clear button	boolean \| { clearIcon?: ReactNode }	false	5.8.0: Support Object type
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>>	-
classNames	Semantic DOM class	Record<SemanticDOM, string>	-	5.25.0
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
~~dropdownRender~~	Customize dropdown content, use `popupRender` instead	(originNode: ReactNode) => ReactNode	-	4.24.0
popupRender	Customize dropdown content	(originNode: ReactNode) => ReactNode	-
~~dropdownStyle~~	The style of dropdown menu, use `styles.popup.root` instead	CSSProperties	-
~~popupClassName~~	The className of dropdown menu, use `classNames.popup.root` instead	string	-	4.23.0
popupMatchSelectWidth	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
getPopupContainer	Parent node of the dropdown. Default to body, if you encountered positioning problems during scroll, try changing to the scrollable area and position relative to it. Example	function(triggerNode)	() => document.body
notFoundContent	Specify content to show when no result matches	ReactNode	-
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
size	The size of the input box	`large` \| `middle` \| `small`	-
value	Selected option	string	-
styles	Semantic DOM style	Record<SemanticDOM, CSSProperties>	-	5.25.0
variant	Variants of input	`outlined` \| `borderless` \| `filled`	`outlined`	5.13.0
virtual	Disable virtual scroll when set to false	boolean	true	4.1.0
onBlur	Called when leaving the component	function()	-
onChange	Called when selecting an option or changing an input value	function(value)	-
~~onDropdownVisibleChange~~	Called when dropdown open, use `onOpenChange` instead	(open: boolean) => void	-
onOpenChange	Called when dropdown open	(open: boolean) => void	-
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
onInputKeyDown	Called when key pressed	(event: KeyboardEvent) => void	-
onPopupScroll	Called when dropdown scrolls	(event: UIEvent) => void	-

Methods

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

Semantic DOM

Design Token

Component TokenHow to use?

Token Name	Description	Type	Default Value
activeBorderColor	Active border color	string	#1677ff
activeOutlineColor	Active outline color	string	rgba(5,145,255,0.1)
clearBg	Background color of clear button	string	#ffffff
hoverBorderColor	Hover border color	string	#4096ff
multipleItemBg	Background color of multiple tag	string	rgba(0,0,0,0.06)
multipleItemBorderColor	Border color of multiple tag	string	transparent
multipleItemBorderColorDisabled	Border color of multiple tag when disabled	string	transparent
multipleItemColorDisabled	Text color of multiple tag when disabled	string	rgba(0,0,0,0.25)
multipleItemHeight	Height of multiple tag	number	24
multipleItemHeightLG	Height of multiple tag with large size	number	32
multipleItemHeightSM	Height of multiple tag with small size	number	16
multipleSelectorBgDisabled	Background color of multiple selector when disabled	string	rgba(0,0,0,0.04)
optionActiveBg	Background color when option is active	string	rgba(0,0,0,0.04)
optionFontSize	Font size of option	number	14
optionHeight	Height of option	number	32
optionLineHeight	Line height of option	undefined \| LineHeight<string \| number>	1.5714285714285714
optionPadding	Padding of option	undefined \| Padding<string \| number>	5px 12px
optionSelectedBg	Background color when option is selected	string	#e6f4ff
optionSelectedColor	Text color when option is selected	string	rgba(0,0,0,0.88)
optionSelectedFontWeight	Font weight when option is selected	undefined \| FontWeight	600
selectorBg	Background color of selector	string	#ffffff
showArrowPaddingInlineEnd	Inline end padding of arrow	number	18
singleItemHeightLG	Height of single selected item with large size	number	40
zIndexPopup	z-index of dropdown	number	1050

Global TokenHow to use?

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

The AutoComplete component is essentially an extension of the Input form element. When the options property is empty, displaying empty text could mislead the user into believing the component is not operational, when in fact they are still able to input text. To avoid confusion, the open property will not display the drop-down menu when set to true and in combination with an empty options property. The open property must be used in conjunction with the options property.