AutoComplete

AutoComplete (자동 완성)

AutoComplete는 셀렉터 대신 입력 박스가 필요하거나, 입력 제안이나 도움 텍스트가 필요할 때 사용하는 컴포넌트예요.

출처: 문서

본문

언제 사용하나요

• 셀렉터 대신 입력 박스가 필요할 때.
• 입력 제안이나 도움 텍스트가 필요할 때.

Select와의 차이점은:

• AutoComplete는 텍스트 힌트가 있는 입력 박스로, 사용자가 자유롭게 입력할 수 있어요. 핵심어는 입력(input) 을 돕는 것이에요.
• Select는 주어진 선택지 중에서 고르는 것이에요. 핵심어는 선택(select) 이에요.

예제 (Examples)

기본 사용 (Basic Usage)

기본 사용법이에요. options 속성으로 autocomplete의 데이터 소스를 설정해요.

import React, { useState } from 'react';
import { AutoComplete } from 'antd';
import type { AutoCompleteProps } from 'antd';

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

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

  const getPanelValue = (searchText: string) =>
    !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}
        showSearch={{
          onSearch: (text) => setOptions(getPanelValue(text)),
        }}
        placeholder="input here"
      />
      <br />
      <br />
      <AutoComplete
        value={value}
        showSearch={{ onSearch: (text) => setAnotherOptions(getPanelValue(text)) }}
        options={anotherOptions}
        style={{ width: 200 }}
        onSelect={onSelect}
        onChange={onChange}
        placeholder="control mode"
      />
    </>
  );
};

export default App;

커스터마이즈 (Customized)

커스텀 Option 레이블을 설정할 수 있어요.

import React from 'react';
import { AutoComplete } from 'antd';
import type { AutoCompleteProps } from 'antd';

const App: React.FC = () => {
  const [options, setOptions] = React.useState<AutoCompleteProps['options']>([]);
  const handleSearch = (value: string) => {
    setOptions(() => {
      if (!value || value.includes('@')) {
        return [];
      }
      return ['gmail.com', '163.com', 'qq.com'].map((domain) => ({
        label: `${value}@${domain}`,
        value: `${value}@${domain}`,
      }));
    });
  };
  return (
    <AutoComplete
      style={{ width: 200 }}
      showSearch={{ onSearch: handleSearch }}
      placeholder="input here"
      options={options}
    />
  );
};

export default App;

Input 컴포넌트 커스터마이즈 (Customize Input Component)

Input 컴포넌트를 커스터마이즈해요.

import React, { useState } from 'react';
import { AutoComplete, Input } from 'antd';
import type { AutoCompleteProps } from 'antd';

const { TextArea } = Input;

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

  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}
      showSearch={{ onSearch: handleSearch }}
    >
      <TextArea
        placeholder="input here"
        className="custom"
        style={{ height: 50 }}
        onKeyPress={handleKeyPress}
      />
    </AutoComplete>
  );
};

export default App;

대소문자 구분 없는 AutoComplete

대소문자를 구분하지 않는 AutoComplete예요.

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`"
    showSearch={{
      filterOption: (inputValue, option) =>
        option!.value.toUpperCase().includes(inputValue.toUpperCase()),
    }}
  />
);

export default App;

조회 패턴 - 특정 카테고리 (Lookup-Patterns - Certain Category)

조회 패턴: 특정 카테고리의 시연이에요. options 속성으로 autocomplete의 옵션을 설정하는 기본 사용법이에요.

import React from 'react';
import { UserOutlined } from '@ant-design/icons';
import { AutoComplete, Flex, Input } from 'antd';
import { createStyles } from 'antd-style';

const useStyles = createStyles((props) => {
  const { css, prefixCls, cssVar } = props;
  return {
    categorySearch: css`
      .${prefixCls}-select-dropdown-menu-item-group-title {
        color: #666;
        font-weight: ${cssVar.fontWeightStrong};
      }
      .${prefixCls}-select-dropdown-menu-item-group {
        border-bottom: ${cssVar.lineWidth} ${cssVar.lineType} #f6f6f6;
      }
      .${prefixCls}-select-dropdown-menu-item {
        padding-inline-start: ${cssVar.padding};
      }
      .${prefixCls}-select-dropdown-menu-item.show-all {
        text-align: center;
        cursor: default;
      }
      .${prefixCls}-select-dropdown-menu {
        max-height: 300px;
      }
    `,
  };
});

const Title: React.FC<Readonly<{ title?: string }>> = (props) => (
  <Flex align="center" justify="space-between">
    {props.title}
    <a href="https://www.google.com/search?q=antd" target="_blank" rel="noopener noreferrer">
      more
    </a>
  </Flex>
);

const renderItem = (title: string, count: number) => ({
  value: title,
  label: (
    <Flex align="center" justify="space-between">
      {title}
      <span>
        <UserOutlined /> {count}
      </span>
    </Flex>
  ),
});

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

const App: React.FC = () => {
  const { styles } = useStyles();
  return (
    <AutoComplete
      classNames={{ popup: { root: styles.categorySearch } }}
      popupMatchSelectWidth={500}
      style={{ width: 250 }}
      options={options}
    >
      <Input.Search size="large" placeholder="input here" />
    </AutoComplete>
  );
};

export default App;

조회 패턴 - 불확정 카테고리 (Lookup-Patterns - Uncertain Category)

조회 패턴: 불확정 카테고리의 시연이에요.

import React, { useState } from 'react';
import { AutoComplete, Input } from 'antd';
import type { AutoCompleteProps } from 'antd';

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

const searchResult = (query: string) =>
  Array.from({ length: 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<AutoCompleteProps['options']>([]);

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

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

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

export default App;

상태 (Status)

status로 AutoComplete에 상태를 추가해요. error나 warning일 수 있어요.

import React, { useState } from 'react';
import { AutoComplete, Space } from 'antd';
import type { AutoCompleteProps } from 'antd';

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

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

  const getPanelValue = (searchText: string) =>
    !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)];

  return (
    <Space vertical style={{ width: '100%' }}>
      <AutoComplete
        options={options}
        showSearch={{
          onSearch: (text) => setOptions(getPanelValue(text)),
        }}
        status="error"
        style={{ width: 200 }}
      />
      <AutoComplete
        options={anotherOptions}
        showSearch={{
          onSearch: (text) => setAnotherOptions(getPanelValue(text)),
        }}
        status="warning"
        style={{ width: 200 }}
      />
    </Space>
  );
};

export default App;

변형 (Variants)

outlined, filled, borderless, underlined 변형 중에서 선택할 수 있어요.

import React, { useState } from 'react';
import { AutoComplete, Flex } from 'antd';
import type { AutoCompleteProps } from 'antd';

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

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

  const getPanelValue = (searchText: string) =>
    !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)];

  return (
    <Flex vertical gap={12}>
      <AutoComplete
        options={options}
        style={{ width: 200 }}
        placeholder="Outlined"
        showSearch={{ onSearch: (text) => setOptions(getPanelValue(text)) }}
        onSelect={globalThis.console.log}
      />
      <AutoComplete
        options={options}
        style={{ width: 200 }}
        placeholder="Filled"
        showSearch={{ onSearch: (text) => setOptions(getPanelValue(text)) }}
        onSelect={globalThis.console.log}
        variant="filled"
      />
      <AutoComplete
        options={options}
        style={{ width: 200 }}
        placeholder="Borderless"
        showSearch={{ onSearch: (text) => setOptions(getPanelValue(text)) }}
        onSelect={globalThis.console.log}
        variant="borderless"
      />
      <AutoComplete
        options={options}
        style={{ width: 200 }}
        placeholder="Underlined"
        onSearch={(text) => setOptions(getPanelValue(text))}
        onSelect={globalThis.console.log}
        variant="underlined"
      />
    </Flex>
  );
};

export default App;

clear 버튼 커스터마이즈 (Customize clear button)

clear 버튼을 커스터마이즈해요.

import React, { useState } from 'react';
import { CloseSquareFilled } from '@ant-design/icons';
import { AutoComplete } from 'antd';
import type { AutoCompleteProps } from 'antd';

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

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

  const getPanelValue = (searchText: string) =>
    !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)];

  return (
    <>
      <AutoComplete
        options={options}
        style={{ width: 200 }}
        showSearch={{ onSearch: (text) => setOptions(getPanelValue(text)) }}
        placeholder="UnClearable"
        allowClear={false}
      />
      <br />
      <br />
      <AutoComplete
        options={options}
        style={{ width: 200 }}
        showSearch={{ onSearch: (text) => setOptions(getPanelValue(text)) }}
        placeholder="Customized clear icon"
        allowClear={{ clearIcon: <CloseSquareFilled /> }}
      />
    </>
  );
};

export default App;

커스텀 시맨틱 DOM 스타일링

classNames와 styles에 객체/함수를 전달해 AutoComplete의 시맨틱 DOM 스타일을 커스터마이즈할 수 있어요.

import React from 'react';
import { AutoComplete, Flex } from 'antd';
import type { AutoCompleteProps, GetProp } from 'antd';
import { createStaticStyles } from 'antd-style';

const classNames = createStaticStyles(({ css }) => ({
  root: css`
    border-radius: 4px;
  `,
}));

const stylesObject: AutoCompleteProps['styles'] = {
  popup: {
    root: { borderWidth: 1, borderColor: '#1890ff' },
    list: { backgroundColor: 'rgba(240,240,240, 0.85)' },
    listItem: { color: '#272727' },
  },
};

const stylesFn: AutoCompleteProps['styles'] = ({
  props,
}): GetProp<AutoCompleteProps, 'styles', 'Return'> => {
  if (props.variant === 'filled') {
    return {
      popup: {
        root: { borderWidth: 1, borderColor: '#ccc' },
        list: { backgroundColor: 'rgba(240,240,240, 0.85)' },
        listItem: { color: '#272727' },
      },
    };
  }
  return {};
};

const options: AutoCompleteProps['options'] = [
  { value: 'Burnaby' },
  { value: 'Seattle' },
  { value: 'Los Angeles' },
  { value: 'San Francisco' },
  { value: 'Meet student' },
];

const App: React.FC = () => {
  const sharedProps: AutoCompleteProps = {
    options,
    classNames: {
      root: classNames.root,
    },
    style: { width: 200 },
  };

  return (
    <Flex vertical gap="medium">
      <AutoComplete {...sharedProps} placeholder="object styles" styles={stylesObject} />
      <AutoComplete
        {...sharedProps}
        variant="filled"
        placeholder="function styles"
        styles={stylesFn}
      />
    </Flex>
  );
};

export default App;

API

공통 props 참고: Common props

속성	설명	타입	기본값	버전
allowClear	clear 버튼 표시	boolean | { clearIcon?: ReactNode }	false	5.8.0: Object 타입 지원
backfill	키보드 사용 시 선택된 항목을 입력으로 되채울지	boolean	false
children	입력 요소 커스터마이즈	HTMLInputElement | HTMLTextAreaElement | React.ReactElement<InputProps>	<Input />
classNames	컴포넌트 내부 각 시맨틱 구조의 클래스 커스터마이즈. 객체 또는 함수 지원	Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string>	-
dataSource	autocomplete 옵션의 데이터 소스, options를 사용하세요	DataSourceItemType[]	-	-
defaultActiveFirstOption	기본적으로 첫 옵션을 활성화할지	boolean	true
defaultOpen	드롭다운의 초기 열림 상태	boolean	-
defaultValue	초기 선택 옵션	string	-
disabled	select 비활성화 여부	boolean	false
dropdownClassName	드롭다운 메뉴의 className, classNames.popup.root를 사용하세요	string	-	-
dropdownMatchSelectWidth	드롭다운 메뉴와 입력이 같은 너비인지, popupMatchSelectWidth를 사용하세요	boolean | number	true	-
dropdownRender	드롭다운 콘텐츠 커스터마이즈, popupRender를 사용하세요	(originNode: ReactElement) => ReactNode	-	4.24.0
popupRender	드롭다운 콘텐츠 커스터마이즈	(originNode: ReactElement) => ReactNode	-
dropdownStyle	드롭다운 메뉴의 스타일, styles.popup.root를 사용하세요	CSSProperties	-
popupClassName	드롭다운 메뉴의 className, classNames.popup.root를 사용하세요	string	-	4.23.0
popupMatchSelectWidth	드롭다운 메뉴와 select 입력이 같은 너비인지 결정. 기본은 min-width를 입력과 같게 설정. 값이 select 너비보다 작으면 무시. false는 가상 스크롤 비활성화	boolean | number	true
filterOption	true면 입력으로 옵션을 필터. 함수면 그 함수로 필터. 함수는 inputValue와 option 두 인자를 받고, true를 반환하면 옵션이 필터 집합에 포함	boolean | function(inputValue, option)	true
getPopupContainer	드롭다운의 부모 노드. 기본은 body. 스크롤 중 위치 문제가 생기면 스크롤 가능 영역으로 바꿔 그에 상대적으로 위치 지정해 보세요	function(triggerNode)	() => document.body
notFoundContent	일치하는 결과가 없을 때 표시할 콘텐츠 지정	ReactNode	-
open	드롭다운의 제어된 열림 상태	boolean	-
options	Select 옵션. jsx 정의보다 성능이 좋음	{ label, value }[]	-
placeholder	입력의 placeholder	string	-
showSearch	검색 설정	true | Object	true
status	검증 상태 설정	'error' | 'warning'	-	4.19.0
size	입력 박스의 크기	large | medium | small	-
value	선택된 옵션	string	-
styles	컴포넌트 내부 각 시맨틱 구조의 인라인 스타일 커스터마이즈. 객체 또는 함수 지원	Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties>	-
variant	입력의 변형	outlined | borderless | filled | underlined	outlined	5.13.0
virtual	false로 설정하면 가상 스크롤 비활성화	boolean	true	4.1.0
onBlur	컴포넌트를 벗어날 때 호출	function()	-
onChange	옵션을 선택하거나 입력 값을 바꿀 때 호출	function(value)	-
onDropdownVisibleChange	드롭다운이 열릴 때 호출, onOpenChange를 사용하세요	(open: boolean) => void	-
onOpenChange	드롭다운이 열릴 때 호출	(open: boolean) => void	-
onFocus	컴포넌트에 들어올 때 호출	function()	-
onSearch	항목을 검색할 때 호출	function(value)	-
onSelect	옵션이 선택될 때 호출. 인자는 옵션의 값과 옵션 인스턴스	function(value, option)	-
onClear	clear할 때 호출	function	-	4.6.0
onInputKeyDown	키를 눌렀을 때 호출	(event: KeyboardEvent) => void	-
onPopupScroll	드롭다운이 스크롤될 때 호출	(event: UIEvent) => void	-

showSearch

속성	설명	타입	기본값	버전
filterOption	true면 입력으로 옵션을 필터. 함수면 그 함수로 필터. 함수는 inputValue와 option 두 인자를 받고, true를 반환하면 옵션이 필터 집합에 포함	boolean | function(inputValue, option)	true
onSearch	항목을 검색할 때 호출	function(value)	-

메서드 (Methods)

이름	설명	버전
blur()	포커스 제거
focus()	포커스 얻기

시맨틱 DOM (Semantic DOM)

https://ant.design/components/auto-complete/semantic.md

디자인 토큰 (Design Token)

컴포넌트 토큰 (Select)

토큰 이름	설명	타입	기본값
activeBorderColor	활성 테두리 색	string	#1677ff
activeOutlineColor	활성 아웃라인 색	string	rgba(5,145,255,0.1)
clearBg	clear 버튼의 배경색	string	#ffffff
hoverBorderColor	호버 테두리 색	string	#4096ff
multipleItemBg	multiple 태그의 배경색	string	rgba(0,0,0,0.06)
multipleItemBorderColor	multiple 태그의 테두리색	string	transparent
multipleItemBorderColorDisabled	비활성 multiple 태그의 테두리색	string	transparent
multipleItemColorDisabled	비활성 multiple 태그의 텍스트 색	string	rgba(0,0,0,0.25)
multipleItemHeight	multiple 태그의 높이	number	24
multipleItemHeightLG	큰 크기 multiple 태그의 높이	number	32
multipleItemHeightSM	작은 크기 multiple 태그의 높이	number	16
multipleSelectorBgDisabled	비활성 multiple 셀렉터의 배경색	string	rgba(0,0,0,0.04)
optionActiveBg	옵션이 활성일 때 배경색	string	rgba(0,0,0,0.04)
optionFontSize	옵션의 폰트 크기	number	14
optionHeight	옵션의 높이	number	32
optionLineHeight	옵션의 줄 높이	LineHeight<string | number> | undefined	1.5714285714285714
optionPadding	옵션의 패딩	Padding<string | number> | undefined	5px 12px
optionSelectedBg	옵션이 선택됐을 때 배경색	string	#e6f4ff
optionSelectedColor	옵션이 선택됐을 때 텍스트 색	string	rgba(0,0,0,0.88)
optionSelectedFontWeight	옵션이 선택됐을 때 폰트 두께	FontWeight | undefined	600
selectorBg	셀렉터의 배경색	string	#ffffff
showArrowPaddingInlineEnd	화살표의 inline end 패딩	number	18
singleItemHeightLG	큰 크기 단일 선택 항목의 높이	number	40
zIndexPopup	드롭다운의 z-index	number	1050

전역 토큰 (Global Token)

토큰 이름	설명	타입	기본값
borderRadius	기본 컴포넌트의 테두리 반지름	number
borderRadiusLG	LG 크기 테두리 반지름, Card, Modal 등 큰 반지름 컴포넌트에 사용	number
borderRadiusSM	SM 크기 테두리 반지름, Button, Input, Select 등 작은 입력 컴포넌트에 사용	number
borderRadiusXS	XS 크기 테두리 반지름, Segmented, Arrow 등 작은 반지름 컴포넌트에 사용	number
boxShadowSecondary	요소의 2차 box shadow 스타일 제어.	string
colorBgContainer	컨테이너 배경색. 예: 기본 버튼, 입력박스 등. colorBgElevated와 혼동하지 말 것.	string
colorBgContainerDisabled	비활성 상태 컨테이너의 배경색 제어.	string
colorBgElevated	팝업 레이어의 컨테이너 배경색, 다크 모드에서 colorBgContainer보다 약간 밝음. 예: modal, pop-up, menu 등	string
colorBorder	기본 테두리색, 요소를 구분하는 데 사용. 예: 폼 구분선, 카드 구분선 등	string
colorBorderDisabled	비활성 상태 요소의 테두리색 제어.	string
colorError	작업 실패의 시각 요소를 나타내는 데 사용. 예: 오류 Button, 오류 Result 컴포넌트 등	string
colorErrorAffix	오류 상태 폼 컨트롤 prefix/suffix의 색 제어.	string
colorErrorBg	오류 상태의 배경색.	string
colorErrorBgHover	오류 상태의 호버 배경색.	string
colorErrorBorderHover	오류 상태의 호버 테두리색.	string
colorErrorOutline	오류 상태 입력 컴포넌트의 아웃라인 색 제어.	string
colorErrorText	오류 색 텍스트의 기본 상태.	string
colorFillQuaternary	네 번째 채움 색 레벨. 얼룩말 무늬, 경계 구분 색 블록 등 주의 끌기 어려운 색 블록에 적합	string
colorFillSecondary	두 번째 채움 색 레벨. Rate, Skeleton 등 요소의 형태를 더 명확히 외곽. 세 번째 채움 색의 Hover 상태로도 사용(Table 등)	string
colorFillTertiary	세 번째 채움 색 레벨. Slider, Segmented 등 요소의 형태 외곽에 사용. 강조 요구가 없으면 기본 채움 색으로 권장	string
colorIcon	약한 액션. 예: allowClear 또는 Alert 닫기 버튼	string
colorIconHover	약한 액션 호버 색. 예: allowClear 또는 Alert 닫기 버튼	string
colorPrimary	브랜드 색. 제품의 특성과 커뮤니케이션을 반영하는 가장 직접적인 시각 요소. 선택하면 완전한 색 팔레트가 자동 생성	string
colorSplit	구분선 색. colorBorderSecondary와 같지만 투명도가 있음.	string
colorText	W3C 표준을 준수하는 기본 텍스트 색. 가장 어두운 중성색이기도 함.	string
colorTextDescription	텍스트 설명의 폰트 색 제어.	string
colorTextDisabled	비활성 상태 텍스트의 색 제어.	string
colorTextPlaceholder	placeholder 텍스트 색 제어.	string
colorTextQuaternary	네 번째 텍스트 색 레벨. 가장 밝은 텍스트 색으로 폼 입력 프롬프트, 비활성 색 텍스트 등에 사용	string
colorWarning	경고 map 토큰. Notification, Alert 등이 사용. Alert 또는 Control 컴포넌트(Input)도 사용	string
colorWarningAffix	경고 상태 폼 컨트롤 prefix/suffix의 색 제어.	string
colorWarningBg	경고 상태의 배경색.	string
colorWarningBgHover	경고 상태의 호버 배경색.	string
colorWarningHover	경고 색의 호버 상태.	string
colorWarningOutline	경고 상태 입력 컴포넌트의 아웃라인 색 제어.	string
controlHeight	Ant Design에서 버튼, 입력박스 같은 기본 컨트롤의 높이	number
controlHeightLG	LG 컴포넌트 높이	number
controlHeightSM	SM 컴포넌트 높이	number
controlItemBgActiveHover	컨트롤 컴포넌트 항목의 호버+활성 배경색 제어.	string
controlOutlineWidth	입력 컴포넌트의 아웃라인 너비 제어.	number
controlPaddingHorizontal	요소의 가로 패딩 제어.	number
fontFamily	시스템 기본 인터페이스 폰트와 화면 표시에 적합한 대체 폰트 라이브러리 세트 제공	string
fontSize	디자인 시스템에서 가장 널리 사용되는 폰트 크기.	number
fontSizeIcon	Select, Cascader 등의 동작 아이콘 폰트 크기 제어. 보통 fontSizeSM과 같음.	number
fontSizeLG	큰 폰트 크기	number
fontSizeSM	작은 폰트 크기	number
lineHeight	텍스트의 줄 높이.	number
lineHeightLG	큰 텍스트의 줄 높이.	number
lineType	기본 컴포넌트의 테두리 스타일	string
lineWidth	기본 컴포넌트의 테두리 너비	number
marginXS	요소의 여백 제어, 작은 크기.	number
motionDurationMid	모션 속도, 중간 속도. 중간 요소 애니메이션 상호작용에 사용.	string
motionDurationSlow	모션 속도, 느린 속도. 대형 요소 애니메이션 상호작용에 사용.	string
motionEaseInOut	프리셋 모션 곡선.	string
motionEaseInOutCirc	프리셋 모션 곡선.	string
motionEaseInQuint	프리셋 모션 곡선.	string
motionEaseOutCirc	프리셋 모션 곡선.	string
motionEaseOutQuint	프리셋 모션 곡선.	string
paddingSM	요소의 작은 패딩 제어.	number
paddingXS	요소의 매우 작은 패딩 제어.	number
paddingXXS	요소의 매우 작은 여분의 패딩 제어.	number

FAQ

제어 모드에서 텍스트 합성 시스템이 onSearch와 잘 동작하지 않는 이유는? {#faq-controlled-onsearch-composition}

제어 상태를 관리하려면 onChange를 사용하세요. onSearch는 검색 입력용으로 onChange와 같지 않아요. 게다가 옵션을 클릭해도 onSearch 이벤트는 트리거되지 않아요.

관련 이슈: #18230 #17916

제어된 open AutoComplete에서 options가 비어 있으면 왜 드롭다운 메뉴가 표시되지 않나요? {#faq-empty-options-controlled-open}

AutoComplete 컴포넌트는 본질적으로 Input 폼 요소의 확장이에요. options 속성이 비어 있을 때 빈 텍스트를 표시하면 사용자가 실제로는 텍스트를 입력할 수 있는데도 컴포넌트가 동작하지 않는 것처럼 오해할 수 있어요. 혼동을 피하기 위해 open 속성은 true로 설정되고 빈 options 속성과 결합될 때 드롭다운 메뉴를 표시하지 않아요. open 속성은 반드시 options 속성과 함께 사용해야 해요.

더 알아보기 (Learn more)

• Select 컴포넌트 — 선택형 vs 자동완성형 비교
• Input 컴포넌트 — 입력 요소
• Ant Design 시작하기 — 프로젝트 설정