logoAnt Design

⌘ K
  • Design
  • Development
  • Components
  • Blog
  • Resources
5.25.0
  • Components Overview
  • General
    • Button
    • FloatButton
      5.0.0
    • Icon
    • Typography
  • Layout
    • Divider
    • Flex
      5.10.0
    • Grid
    • Layout
    • Space
    • Splitter
      5.21.0
  • Navigation
    • Anchor
    • Breadcrumb
    • Dropdown
    • Menu
    • Pagination
    • Steps
    • Tabs
  • Data Entry
    • AutoComplete
    • Cascader
    • Checkbox
    • ColorPicker
      5.5.0
    • DatePicker
    • Form
    • Input
    • InputNumber
    • Mentions
    • Radio
    • Rate
    • Select
    • Slider
    • Switch
    • TimePicker
    • Transfer
    • TreeSelect
    • Upload
  • Data Display
    • Avatar
    • Badge
    • Calendar
    • Card
    • Carousel
    • Collapse
    • Descriptions
    • Empty
    • Image
    • List
    • Popover
    • QRCode
      5.1.0
    • Segmented
    • Statistic
    • Table
    • Tag
    • Timeline
    • Tooltip
    • Tour
      5.0.0
    • Tree
  • Feedback
    • Alert
    • Drawer
    • Message
    • Modal
    • Notification
    • Popconfirm
    • Progress
    • Result
    • Skeleton
    • Spin
    • Watermark
      5.1.0
  • Other
    • Affix
    • App
      5.1.0
    • ConfigProvider
    • Util
      5.13.0

AutoComplete

Autocomplete function of input field.
Importimport { AutoComplete } from "antd";
Sourcecomponents/auto-complete
Docs
Edit this pageChangelog

Resources

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-Landing Templates
Scaffolds-Scaffold Market
Umi-React Application Framework
dumi-Component doc generator
qiankun-Micro-Frontends Framework
Ant Motion-Motion Solution
China Mirror 🇨🇳

Community

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design in YuQue
Ant Design in Zhihu
Experience Cloud Blog
seeconf logoSEE Conf-Experience Tech Conference

Help

GitHub
Change Log
FAQ
Bug Report
Issues
Discussions
StackOverflow
SegmentFault

Ant XTech logoMore Products

yuque logoYuQue-Document Collaboration Platform
AntV logoAntV-Data Visualization
Egg logoEgg-Enterprise Node.js Framework
Kitchen logoKitchen-Sketch Toolkit
Galacean logoGalacean-Interactive Graphics Solution
xtech logoAnt Financial Experience Tech
Theme Editor
Made with ❤ by
Ant Group and Ant Design Community
loading

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

PropertyDescriptionTypeDefaultVersion
allowClearShow clear buttonboolean | { clearIcon?: ReactNode }false5.8.0: Support Object type
autoFocusIf get focus when component mountedbooleanfalse
backfillIf backfill selected item the input when using keyboardbooleanfalse
children (for customize input element)Customize input elementHTMLInputElement | HTMLTextAreaElement | React.ReactElement<InputProps><Input />
children (for dataSource)Data source to auto completeReact.ReactElement<OptionProps> | Array<React.ReactElement<OptionProps>>-
classNamesSemantic DOM classRecord<SemanticDOM, string>-5.25.0
defaultActiveFirstOptionWhether active first option by defaultbooleantrue
defaultOpenInitial open state of dropdownboolean-
defaultValueInitial selected optionstring-
disabledWhether disabled selectbooleanfalse
dropdownRenderCustomize dropdown content, use popupRender instead(originNode: ReactNode) => ReactNode-4.24.0
popupRenderCustomize dropdown content(originNode: ReactNode) => ReactNode-
dropdownStyleThe style of dropdown menu, use styles.popup.root insteadCSSProperties-
popupClassNameThe className of dropdown menu, use classNames.popup.root insteadstring-4.23.0
popupMatchSelectWidthDetermine 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 scrollboolean | numbertrue
filterOptionIf 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 excludedboolean | function(inputValue, option)true
getPopupContainerParent 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. Examplefunction(triggerNode)() => document.body
notFoundContentSpecify content to show when no result matchesReactNode-
openControlled open state of dropdownboolean-
optionsSelect options. Will get better perf than jsx definition{ label, value }[]-
placeholderThe placeholder of inputstring-
statusSet validation status'error' | 'warning'-4.19.0
sizeThe size of the input boxlarge | middle | small-
valueSelected optionstring-
stylesSemantic DOM styleRecord<SemanticDOM, CSSProperties>-5.25.0
variantVariants of inputoutlined | borderless | filledoutlined5.13.0
virtualDisable virtual scroll when set to falsebooleantrue4.1.0
onBlurCalled when leaving the componentfunction()-
onChangeCalled when selecting an option or changing an input valuefunction(value)-
onDropdownVisibleChangeCalled when dropdown open, use onOpenChange instead(open: boolean) => void-
onOpenChangeCalled when dropdown open(open: boolean) => void-
onFocusCalled when entering the componentfunction()-
onSearchCalled when searching itemsfunction(value)-
onSelectCalled when a option is selected. param is option's value and option instancefunction(value, option)-
onClearCalled when clearfunction-4.6.0
onInputKeyDownCalled when key pressed(event: KeyboardEvent) => void-
onPopupScrollCalled when dropdown scrolls(event: UIEvent) => void-

Methods

NameDescriptionVersion
blur()Remove focus
focus()Get focus

Semantic DOM

Design Token

Component TokenHow to use?
Token NameDescriptionTypeDefault Value
activeBorderColorActive border colorstring#1677ff
activeOutlineColorActive outline colorstringrgba(5,145,255,0.1)
clearBgBackground color of clear buttonstring#ffffff
hoverBorderColorHover border colorstring#4096ff
multipleItemBgBackground color of multiple tagstringrgba(0,0,0,0.06)
multipleItemBorderColorBorder color of multiple tagstringtransparent
multipleItemBorderColorDisabledBorder color of multiple tag when disabledstringtransparent
multipleItemColorDisabledText color of multiple tag when disabledstringrgba(0,0,0,0.25)
multipleItemHeightHeight of multiple tagnumber24
multipleItemHeightLGHeight of multiple tag with large sizenumber32
multipleItemHeightSMHeight of multiple tag with small sizenumber16
multipleSelectorBgDisabledBackground color of multiple selector when disabledstringrgba(0,0,0,0.04)
optionActiveBgBackground color when option is activestringrgba(0,0,0,0.04)
optionFontSizeFont size of optionnumber14
optionHeightHeight of optionnumber32
optionLineHeightLine height of optionundefined | LineHeight<string | number>1.5714285714285714
optionPaddingPadding of optionundefined | Padding<string | number>5px 12px
optionSelectedBgBackground color when option is selectedstring#e6f4ff
optionSelectedColorText color when option is selectedstringrgba(0,0,0,0.88)
optionSelectedFontWeightFont weight when option is selectedundefined | FontWeight600
selectorBgBackground color of selectorstring#ffffff
showArrowPaddingInlineEndInline end padding of arrownumber18
singleItemHeightLGHeight of single selected item with large sizenumber40
zIndexPopupz-index of dropdownnumber1050
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

Why won't a controlled open AutoComplete display a drop-down menu when options are empty?

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.

Basic Usage

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customize Input Component

Customize Input Component

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Lookup-Patterns - Certain Category

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Status

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customize clear button

Customize clear button

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customized

You could set custom Option label

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Non-case-sensitive AutoComplete

A non-case-sensitive AutoComplete

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Lookup-Patterns - Uncertain Category

Demonstration of Lookup Patterns: Uncertain Category.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Variants

There are outlined filled and borderless, totally three variants to choose from.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
input here


control mode
UnClearable


Customized clear icon
input here
try to type `b`
Outlined
Filled
Borderless
input here
  • root
    5.25.0
    Root element
  • popup.root
    5.25.0
    Popup element