Ant Design

⌘ K

5.21.3

Select

선택 항목을 표시하는 드롭다운 메뉴.

가져오기import{ Select }from"antd";

소스components/select

문서

이 페이지 수정 변경 로그

Ant Design

⌘ K

5.21.3

Select

선택 항목을 표시하는 드롭다운 메뉴.

가져오기import{ Select }from"antd";

소스components/select

문서

이 페이지 수정 변경 로그

사용 시기

선택 항목을 표시하는 드롭다운 메뉴 - 기본 <select> 태그의 세련된 대안
선택지가 5개 미만일 때 Radio 컴포넌트가 권장 됩니다.
입력이 가능하면서 선택할 수도 있는 입력 상자를 원한다면 AutoComplete가 필요할 수 있습니다.

버전 5.11.0 이후 사용 방식 업그레이드

업그레이드 팁

5.11.0 버전 이후, 더 향상된 성능과 간소화된 코드 스타일을 만들 수 있는 <Select options={[... ]}> 을 제공합니다. 동시에 이전 버전은 더 이상 브라우저 콘솔에서 제공되지 않을 것이며, antd 6.0 버전에서 제거될 예정입니다.

// works when >=5.11.0, recommended ✅
return <Select options={[{ value: 'sample', label: <span>sample</span> }]} />;

// works when <5.11.0, deprecated when >=5.11.0 🙅🏻‍♀️
return (
  <Select onChange={onChange}>
    <Select.Option value="sample">Sample</Select.Option>
  </Select>
);

사용 예시

API

공통 props 레퍼런스 Common props

Select props

Property	Description	Type	Default	Version
allowClear	사용자 정의 초기화 아이콘을 설정 가능하게 해줍니다.	boolean \| { clearIcon?: ReactNode }	false	5.8.0: Support object type
autoClearSearchValue	항목을 선택할 때 현재 검색어가 지워질 지 여부를 설정할 수 있습니다. 이 옵션은 `mode`가 `multiple` 또는 `tags` 로 설정된 경우에만 적용됩니다.	boolean	true
autoFocus	기본으로 포커스가 설정됩니다.	boolean	false
defaultActiveFirstOption	기본적으로 첫 번째 옵션을 활성화 할 지 여부를 설정할 수 있습니다.	boolean	true
defaultOpen	드롭다운을 열었을 때 초기 상태 설정 여부를 설정할 수 있습니다.	boolean	-
defaultValue	초기 선택 옵션	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
disabled	비활성화 여부를 선택할 수 있습니다.	boolean	false
popupClassName	드롭다운 메뉴의 `className`을 설정할 수 있습니다.	string	-	4.23.0
popupMatchSelectWidth	팝업 메뉴와 선택 입력이 같은 width 값인지 확인합니다. 기본값은 `min-width` 입력과 동일하게 설정됩니다. 값이 선택 width 보다 작으면 무시합니다. `false` 가상 스크롤을 비활성화 합니다.	boolean \| number	true	5.5.0
dropdownRender	사용자 정의 드롭다운 콘텐츠를 만들 수 있습니다.	(originNode: ReactNode) => ReactNode	-
dropdownStyle	드롭다운 메뉴의 스타일을 정의할 수 있습니다.	CSSProperties	-
fieldNames	사용자 정의 노드 레이블, 값 , 옵션, 그룹 레이블 필드 이름을 만들 수 있습니다.	object	{ label: `label`, value: `value`, options: `options`, groupLabel: `label` }	4.17.0 (`groupLabel` added in 5.6.0)
filterOption	true일 경우, 입력 값으로 옵션을 필터링하며, 함수일 경우 해당 함수로 옵션을 필터링합니다. 함수는 두 가지 인자(`inputValue`와 `option`)를 받고, 함수가 `true`를 반환하면 해당 옵션은 필터링된 세트에 포함되며, 그렇지 않으면 제외됩니다.	boolean \| function(inputValue, option)	true
filterSort	검색 옵션을 정렬하기 위한 정렬 함수. Array.sort's compareFunction을 참조하세요.	(optionA: Option, optionB: Option, info: { searchValue: string }) => number	-	`searchValue`: 5.19.0
getPopupContainer	선택기(selector)가 렌더링될 상위 노드를 지정합니다. 기본값은 `body`입니다. 위치 문제가 발생하면 스크롤 가능한 콘텐츠로 수정하고 상대적으로 위치를 지정해보세요. 예시	function(triggerNode)	() => document.body
labelInValue	label을 value에 포함할 지 여부를 설정합니다. 이 경우 value의 형식이 문자열에서 { value: string, label: ReactNode }로 변경됩니다.	boolean	false
listHeight	팝업 높이를 설정합니다.	number	256
loading	로딩 상태를 나타냅니다.	boolean	false
maxCount	선택할 수 있는 항목의 최대 개수를 설정합니다. 이 속성은 `mode`가 `multiple` 또는 `tags`일 때만 적용됩니다.	number	-	5.13.0
maxTagCount	표시할 최대 tag 수를 설정합니다. `responsive` 모드는 렌더링 성능에 영향을 줄 수 있습니다.	number \| `responsive`	-	responsive: 4.10
maxTagPlaceholder	tag를 표시하지 않을 때의 플레이스홀더입니다.	ReactNode \| function(omittedValues)	-
maxTagTextLength	표시할 tag 텍스트의 최대 길이를 설정합니다.	number	-
menuItemSelectedIcon	다중 선택 옵션에서 선택된 메뉴 아이템의 사용자 정의 아이콘을 설정합니다.	ReactNode	-
mode	Select의 모드를 설정합니다.	`multiple` \| `tags`	-
notFoundContent	결과가 일치하지 않을 때 표시할 내용을 지정합니다.	ReactNode	`Not Found`
open	드롭다운의 열림 상태를 제어합니다.	boolean	-
optionFilterProp	`filterOption`이 `true`일 때 필터링에 사용할 옵션 속성의 값을 지정합니다. `options`가 설정되면 `label`로 설정되어야 합니다.	string	`value`
optionLabelProp	옵션의 어떤 속성이 Select의 내용으로 렌더링 될 지를 지정합니다. 예시	string	`children`
options	옵션을 선택합니다. jsx 정의보다 성능이 더 좋습니다.	{ label, value }[]	-
optionRender	드롭다운 옵션을 사용자 정의 하여 렌더링합니다.	(option: FlattenOptionData<BaseOptionType> , info: { index: number }) => React.ReactNode	-	5.11.0
placeholder	Select의 플레이스홀더입니다.	ReactNode	-
placement	선택 상자가 팝업되는 위치를 설정합니다.	`bottomLeft` `bottomRight` `topLeft` `topRight`	bottomLeft
removeIcon	사용자 정의 제거 아이콘입니다.	ReactNode	-
searchValue	현재 입력된 "검색" 텍스트입니다.	string	-
showSearch	선택이 가능한지 여부를 설정합니다.	boolean	single: false, multiple: true
size	Select 입력의 크기를 설정합니다.	`large` \| `middle` \| `small`	`middle`
status	유효성 상태를 설정합니다.	'error' \| 'warning'	-	4.19.0
suffixIcon	사용자 정의 접미사 아이콘입니다. 사용자 정의된 아이콘은 상호작용을 위해 클릭을 허용하지 않으며, `pointer-events: none` 스타일을 사용하여 이를 우회할 수 있습니다.	ReactNode	`<DownOutlined />`
tagRender	태그 렌더링을 사용자 정의할 수 있습니다. 이 속성은 `mode` 가 `multiple` 또는 `tags` 일 때만 적용됩니다.	(props) => ReactNode	-
labelRender	선택된 레이블 렌더링을 사용자 정의할 수 있습니다. (LabelInValueType 정의는 LabelInValueType참조)	(props: LabelInValueType) => ReactNode	-	5.15.0
tokenSeparators	구분자로 사용되는 기호를 지정합니다. 이 속성은 `mode="tags"` 일 때만 적용됩니다.	string[]	-
value	현재 선택된 옵션(변경할 수 없는 배열로 간주됨)입니다.	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
variant	선택기(selector)의 다양한 변형을 제공합니다.	`outlined` \| `borderless` \| `filled`	`outlined`	5.13.0
virtual	false로 설정하면 가상 스크롤을 비활성화합니다.	boolean	true	4.1.0
onBlur	Blur 시 호출됩니다.	function	-
onChange	옵션을 선택하거나 입력 값이 변경될 때 호출됩니다.	function(value, option:Option \| Array<Option>)	-
onClear	초기화될 때 호출됩니다.	function	-	4.6.0
onDeselect	선택이 해제될 때 호출됩니다. 매개변수는 선택된 옵션의 값입니다. `multiple` 또는 `tags` 모드에서만 호출되며, 해당 모드에서만 유효합니다.	function(value: string \| number \| LabeledValue)	-
onDropdownVisibleChange	드롭다운이 열릴 때 호출됩니다.	(open: boolean) => void	-
onFocus	포커스가 잡힐 때 호출됩니다.	(event: FocusEvent) => void	-
onInputKeyDown	키가 눌렸을 때 호출됩니다.	(event: KeyboardEvent) => void	-
onPopupScroll	드롭다운이 스크롤 될 때 호출됩니다.	(event: UIEvent) => void	-
onSearch	입력 값이 변경되면 호출되는 콜백 함수입니다.	function(value: string)	-
onSelect	옵션이 선택되었을 때 호출됩니다. 매개변수는 옵션의 값(또는 키)과 옵션 인스턴스입니다.	function(value: string \| number \| LabeledValue, option: Option)	-

참고 : 드롭다운 메뉴가 페이지와 함께 스크롤되거나 다른 팝업 레이어에서 Select를 트리거해야 할 경우, getPopupContainer={triggerNode => triggerNode.parentElement}를 사용하여 드롭다운 팝업의 렌더링 노드를 트리거 요소의 부모 요소로 고정하는 방법을 시도해보세요.

Select Methods

Name	Description	Version
blur()	포커스 제거
focus()	포커스 얻기

Option props

Property	Description	Type	Default
className	옵션에 추가되는 클래스	string	-
disabled	이 옵션을 비활성화	boolean	false
title	Select 옵션의 `title` 속성	string	-
value	기본적으로 이 속성을 사용해 필터링	string \| number	-

OptGroup props

Property	Description	Type	Default
key	그룹 키	string	-
label	그룹 레이블	React.ReactNode	-
className	옵션에 추가되는 클래스	string	-
title	Select 옵션의 `title` 속성	string	-

Design Token

컴포넌트 토큰어떻게 사용하나요?

토큰 이름	설명	타입	기본값
activeBorderColor	激活态边框色	string	#1677ff
activeOutlineColor	激活态 outline 颜色	string	rgba(5, 145, 255, 0.1)
clearBg	지우기 버튼의 배경색	string	#ffffff
hoverBorderColor	悬浮态边框色	string	#4096ff
multipleItemBg	다중 선택 태그의 배경색	string	rgba(0, 0, 0, 0.06)
multipleItemBorderColor	다중 선택 태그의 테두리 색상	string	transparent
multipleItemBorderColorDisabled	비활성화된 경우 다중 선택 태그의 테두리 색상	string	transparent
multipleItemColorDisabled	비활성화된 경우 다중 선택 태그의 텍스트 색상	string	rgba(0, 0, 0, 0.25)
multipleItemHeight	다중 선택 태그의 높이	number	24
multipleItemHeightLG	큰 크기의 다중 선택 태그의 높이	number	32
multipleItemHeightSM	작은 크기의 다중 선택 태그의 높이	number	16
multipleSelectorBgDisabled	비활성화된 경우 다중 선택기의 배경색	string	rgba(0, 0, 0, 0.04)
optionActiveBg	옵션이 활성화된 경우 배경색	string	rgba(0, 0, 0, 0.04)
optionFontSize	옵션의 글꼴 크기	number	14
optionHeight	옵션의 높이	number	32
optionLineHeight	옵션의 줄 높이	undefined \| LineHeight<string \| number>	1.5714285714285714
optionPadding	옵션의 패딩	undefined \| Padding<string \| number>	5px 12px
optionSelectedBg	옵션이 선택된 경우 배경색	string	#e6f4ff
optionSelectedColor	옵션이 선택된 경우 텍스트 색상	string	rgba(0, 0, 0, 0.88)
optionSelectedFontWeight	옵션이 선택된 경우 글꼴 두께	undefined \| FontWeight	600
selectorBg	선택기의 배경색	string	#ffffff
showArrowPaddingInlineEnd	화살표의 인라인 끝 패딩	number	18
singleItemHeightLG	큰 크기의 단일 선택된 항목의 높이	number	40
zIndexPopup	드롭다운의 z-index	number	1050

글로벌 토큰어떻게 사용하나요?

FAQ

왜 `tags` 모드에서 검색 시 동일합 옵션이 2개씩 나타날 때가 있나요?

이것은 옵션의 label과 value가 다를 때 발생합니다. 필터링 로직을 변경하기 위해 optionFilterProp="label"을 사용할 수 있습니다.

`dropdownRender`에서 요소를 클릭했을 때 드롭다운이 닫히지 않는 이유는 무엇인가요?

open 속성을 사용하여 드롭다운의 열림 상태를 제어할 수 있습니다. open prop: codesandbox.

`dropdownRender`안에서 클릭해도 드롭다운이 닫히지 않도록 하려면 어떻게 하나요?

Select 컴포넌트는 포커스를 잃으면 닫힙니다. 이벤트를 수동으로 처리하여 이 동작을 방지할 수 있습니다.:

<Select
  dropdownRender={() => (
    <div
      onMouseDown={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
    >
      Some Content
    </div>
  )}
/>

왜 커스텀(사용자 정의) 옵션을 사용할 때 스크롤이 깨질 때가 있나요?

가상 스크롤을 각 항목의 높이를 기본적으로 24px로 설정합니다. 옵션의 높이가 다를 경우, listItemHeight와 listHeight를 조정하여 리스트 컨테이너의 높이를 설정해야 합니다.:

<Select listItemHeight={10} listHeight={250} />

참고: listItemHeight와 listHeight는 내부 속성입니다. 꼭 필요할 때만 수정하세요.

왜 a11y 테스트 보고서에서 `aria-` 속성이 누락되나요?

Select는 조작 중일 때만 접근성을 위한 보조 노드를 생성합니다. Select를 열고 다시 시도해보세요. aria-label 및 aria-labelledby 경고가 발생할 경우, 필요한 속성을 사용자의 요구에 맞게 Select에 추가하세요.

기본 가상 스크롤링은 접근성 바인딩을 시뮬레이션하기 위한 모의 요소를 생성합니다. 스크린 리더가 전체 목록에 완전히 접근해야 할 경우, virtual={false}로 설정하여 가상 스크롤링을 비활성화하면 접근성 옵션이 실제 요소에 바인딩됩니다.

사용 시기

선택 항목을 표시하는 드롭다운 메뉴 - 기본 <select> 태그의 세련된 대안
선택지가 5개 미만일 때 Radio 컴포넌트가 권장 됩니다.
입력이 가능하면서 선택할 수도 있는 입력 상자를 원한다면 AutoComplete가 필요할 수 있습니다.

버전 5.11.0 이후 사용 방식 업그레이드

업그레이드 팁

5.11.0 버전 이후, 더 향상된 성능과 간소화된 코드 스타일을 만들 수 있는 <Select options={[... ]}> 을 제공합니다. 동시에 이전 버전은 더 이상 브라우저 콘솔에서 제공되지 않을 것이며, antd 6.0 버전에서 제거될 예정입니다.

// works when >=5.11.0, recommended ✅
return <Select options={[{ value: 'sample', label: <span>sample</span> }]} />;

// works when <5.11.0, deprecated when >=5.11.0 🙅🏻‍♀️
return (
  <Select onChange={onChange}>
    <Select.Option value="sample">Sample</Select.Option>
  </Select>
);

사용 예시

API

공통 props 레퍼런스 Common props

Select props

Property	Description	Type	Default	Version
allowClear	사용자 정의 초기화 아이콘을 설정 가능하게 해줍니다.	boolean \| { clearIcon?: ReactNode }	false	5.8.0: Support object type
autoClearSearchValue	항목을 선택할 때 현재 검색어가 지워질 지 여부를 설정할 수 있습니다. 이 옵션은 `mode`가 `multiple` 또는 `tags` 로 설정된 경우에만 적용됩니다.	boolean	true
autoFocus	기본으로 포커스가 설정됩니다.	boolean	false
defaultActiveFirstOption	기본적으로 첫 번째 옵션을 활성화 할 지 여부를 설정할 수 있습니다.	boolean	true
defaultOpen	드롭다운을 열었을 때 초기 상태 설정 여부를 설정할 수 있습니다.	boolean	-
defaultValue	초기 선택 옵션	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
disabled	비활성화 여부를 선택할 수 있습니다.	boolean	false
popupClassName	드롭다운 메뉴의 `className`을 설정할 수 있습니다.	string	-	4.23.0
popupMatchSelectWidth	팝업 메뉴와 선택 입력이 같은 width 값인지 확인합니다. 기본값은 `min-width` 입력과 동일하게 설정됩니다. 값이 선택 width 보다 작으면 무시합니다. `false` 가상 스크롤을 비활성화 합니다.	boolean \| number	true	5.5.0
dropdownRender	사용자 정의 드롭다운 콘텐츠를 만들 수 있습니다.	(originNode: ReactNode) => ReactNode	-
dropdownStyle	드롭다운 메뉴의 스타일을 정의할 수 있습니다.	CSSProperties	-
fieldNames	사용자 정의 노드 레이블, 값 , 옵션, 그룹 레이블 필드 이름을 만들 수 있습니다.	object	{ label: `label`, value: `value`, options: `options`, groupLabel: `label` }	4.17.0 (`groupLabel` added in 5.6.0)
filterOption	true일 경우, 입력 값으로 옵션을 필터링하며, 함수일 경우 해당 함수로 옵션을 필터링합니다. 함수는 두 가지 인자(`inputValue`와 `option`)를 받고, 함수가 `true`를 반환하면 해당 옵션은 필터링된 세트에 포함되며, 그렇지 않으면 제외됩니다.	boolean \| function(inputValue, option)	true
filterSort	검색 옵션을 정렬하기 위한 정렬 함수. Array.sort's compareFunction을 참조하세요.	(optionA: Option, optionB: Option, info: { searchValue: string }) => number	-	`searchValue`: 5.19.0
getPopupContainer	선택기(selector)가 렌더링될 상위 노드를 지정합니다. 기본값은 `body`입니다. 위치 문제가 발생하면 스크롤 가능한 콘텐츠로 수정하고 상대적으로 위치를 지정해보세요. 예시	function(triggerNode)	() => document.body
labelInValue	label을 value에 포함할 지 여부를 설정합니다. 이 경우 value의 형식이 문자열에서 { value: string, label: ReactNode }로 변경됩니다.	boolean	false
listHeight	팝업 높이를 설정합니다.	number	256
loading	로딩 상태를 나타냅니다.	boolean	false
maxCount	선택할 수 있는 항목의 최대 개수를 설정합니다. 이 속성은 `mode`가 `multiple` 또는 `tags`일 때만 적용됩니다.	number	-	5.13.0
maxTagCount	표시할 최대 tag 수를 설정합니다. `responsive` 모드는 렌더링 성능에 영향을 줄 수 있습니다.	number \| `responsive`	-	responsive: 4.10
maxTagPlaceholder	tag를 표시하지 않을 때의 플레이스홀더입니다.	ReactNode \| function(omittedValues)	-
maxTagTextLength	표시할 tag 텍스트의 최대 길이를 설정합니다.	number	-
menuItemSelectedIcon	다중 선택 옵션에서 선택된 메뉴 아이템의 사용자 정의 아이콘을 설정합니다.	ReactNode	-
mode	Select의 모드를 설정합니다.	`multiple` \| `tags`	-
notFoundContent	결과가 일치하지 않을 때 표시할 내용을 지정합니다.	ReactNode	`Not Found`
open	드롭다운의 열림 상태를 제어합니다.	boolean	-
optionFilterProp	`filterOption`이 `true`일 때 필터링에 사용할 옵션 속성의 값을 지정합니다. `options`가 설정되면 `label`로 설정되어야 합니다.	string	`value`
optionLabelProp	옵션의 어떤 속성이 Select의 내용으로 렌더링 될 지를 지정합니다. 예시	string	`children`
options	옵션을 선택합니다. jsx 정의보다 성능이 더 좋습니다.	{ label, value }[]	-
optionRender	드롭다운 옵션을 사용자 정의 하여 렌더링합니다.	(option: FlattenOptionData<BaseOptionType> , info: { index: number }) => React.ReactNode	-	5.11.0
placeholder	Select의 플레이스홀더입니다.	ReactNode	-
placement	선택 상자가 팝업되는 위치를 설정합니다.	`bottomLeft` `bottomRight` `topLeft` `topRight`	bottomLeft
removeIcon	사용자 정의 제거 아이콘입니다.	ReactNode	-
searchValue	현재 입력된 "검색" 텍스트입니다.	string	-
showSearch	선택이 가능한지 여부를 설정합니다.	boolean	single: false, multiple: true
size	Select 입력의 크기를 설정합니다.	`large` \| `middle` \| `small`	`middle`
status	유효성 상태를 설정합니다.	'error' \| 'warning'	-	4.19.0
suffixIcon	사용자 정의 접미사 아이콘입니다. 사용자 정의된 아이콘은 상호작용을 위해 클릭을 허용하지 않으며, `pointer-events: none` 스타일을 사용하여 이를 우회할 수 있습니다.	ReactNode	`<DownOutlined />`
tagRender	태그 렌더링을 사용자 정의할 수 있습니다. 이 속성은 `mode` 가 `multiple` 또는 `tags` 일 때만 적용됩니다.	(props) => ReactNode	-
labelRender	선택된 레이블 렌더링을 사용자 정의할 수 있습니다. (LabelInValueType 정의는 LabelInValueType참조)	(props: LabelInValueType) => ReactNode	-	5.15.0
tokenSeparators	구분자로 사용되는 기호를 지정합니다. 이 속성은 `mode="tags"` 일 때만 적용됩니다.	string[]	-
value	현재 선택된 옵션(변경할 수 없는 배열로 간주됨)입니다.	string \| string[] \| number \| number[] \| LabeledValue \| LabeledValue[]	-
variant	선택기(selector)의 다양한 변형을 제공합니다.	`outlined` \| `borderless` \| `filled`	`outlined`	5.13.0
virtual	false로 설정하면 가상 스크롤을 비활성화합니다.	boolean	true	4.1.0
onBlur	Blur 시 호출됩니다.	function	-
onChange	옵션을 선택하거나 입력 값이 변경될 때 호출됩니다.	function(value, option:Option \| Array<Option>)	-
onClear	초기화될 때 호출됩니다.	function	-	4.6.0
onDeselect	선택이 해제될 때 호출됩니다. 매개변수는 선택된 옵션의 값입니다. `multiple` 또는 `tags` 모드에서만 호출되며, 해당 모드에서만 유효합니다.	function(value: string \| number \| LabeledValue)	-
onDropdownVisibleChange	드롭다운이 열릴 때 호출됩니다.	(open: boolean) => void	-
onFocus	포커스가 잡힐 때 호출됩니다.	(event: FocusEvent) => void	-
onInputKeyDown	키가 눌렸을 때 호출됩니다.	(event: KeyboardEvent) => void	-
onPopupScroll	드롭다운이 스크롤 될 때 호출됩니다.	(event: UIEvent) => void	-
onSearch	입력 값이 변경되면 호출되는 콜백 함수입니다.	function(value: string)	-
onSelect	옵션이 선택되었을 때 호출됩니다. 매개변수는 옵션의 값(또는 키)과 옵션 인스턴스입니다.	function(value: string \| number \| LabeledValue, option: Option)	-

참고 : 드롭다운 메뉴가 페이지와 함께 스크롤되거나 다른 팝업 레이어에서 Select를 트리거해야 할 경우, getPopupContainer={triggerNode => triggerNode.parentElement}를 사용하여 드롭다운 팝업의 렌더링 노드를 트리거 요소의 부모 요소로 고정하는 방법을 시도해보세요.

Select Methods

Name	Description	Version
blur()	포커스 제거
focus()	포커스 얻기

Option props

Property	Description	Type	Default
className	옵션에 추가되는 클래스	string	-
disabled	이 옵션을 비활성화	boolean	false
title	Select 옵션의 `title` 속성	string	-
value	기본적으로 이 속성을 사용해 필터링	string \| number	-

OptGroup props

Property	Description	Type	Default
key	그룹 키	string	-
label	그룹 레이블	React.ReactNode	-
className	옵션에 추가되는 클래스	string	-
title	Select 옵션의 `title` 속성	string	-

Design Token

컴포넌트 토큰어떻게 사용하나요?

토큰 이름	설명	타입	기본값
activeBorderColor	激活态边框色	string	#1677ff
activeOutlineColor	激活态 outline 颜色	string	rgba(5, 145, 255, 0.1)
clearBg	지우기 버튼의 배경색	string	#ffffff
hoverBorderColor	悬浮态边框色	string	#4096ff
multipleItemBg	다중 선택 태그의 배경색	string	rgba(0, 0, 0, 0.06)
multipleItemBorderColor	다중 선택 태그의 테두리 색상	string	transparent
multipleItemBorderColorDisabled	비활성화된 경우 다중 선택 태그의 테두리 색상	string	transparent
multipleItemColorDisabled	비활성화된 경우 다중 선택 태그의 텍스트 색상	string	rgba(0, 0, 0, 0.25)
multipleItemHeight	다중 선택 태그의 높이	number	24
multipleItemHeightLG	큰 크기의 다중 선택 태그의 높이	number	32
multipleItemHeightSM	작은 크기의 다중 선택 태그의 높이	number	16
multipleSelectorBgDisabled	비활성화된 경우 다중 선택기의 배경색	string	rgba(0, 0, 0, 0.04)
optionActiveBg	옵션이 활성화된 경우 배경색	string	rgba(0, 0, 0, 0.04)
optionFontSize	옵션의 글꼴 크기	number	14
optionHeight	옵션의 높이	number	32
optionLineHeight	옵션의 줄 높이	undefined \| LineHeight<string \| number>	1.5714285714285714
optionPadding	옵션의 패딩	undefined \| Padding<string \| number>	5px 12px
optionSelectedBg	옵션이 선택된 경우 배경색	string	#e6f4ff
optionSelectedColor	옵션이 선택된 경우 텍스트 색상	string	rgba(0, 0, 0, 0.88)
optionSelectedFontWeight	옵션이 선택된 경우 글꼴 두께	undefined \| FontWeight	600
selectorBg	선택기의 배경색	string	#ffffff
showArrowPaddingInlineEnd	화살표의 인라인 끝 패딩	number	18
singleItemHeightLG	큰 크기의 단일 선택된 항목의 높이	number	40
zIndexPopup	드롭다운의 z-index	number	1050

글로벌 토큰어떻게 사용하나요?

FAQ

왜 `tags` 모드에서 검색 시 동일합 옵션이 2개씩 나타날 때가 있나요?

이것은 옵션의 label과 value가 다를 때 발생합니다. 필터링 로직을 변경하기 위해 optionFilterProp="label"을 사용할 수 있습니다.

`dropdownRender`에서 요소를 클릭했을 때 드롭다운이 닫히지 않는 이유는 무엇인가요?

open 속성을 사용하여 드롭다운의 열림 상태를 제어할 수 있습니다. open prop: codesandbox.

`dropdownRender`안에서 클릭해도 드롭다운이 닫히지 않도록 하려면 어떻게 하나요?

Select 컴포넌트는 포커스를 잃으면 닫힙니다. 이벤트를 수동으로 처리하여 이 동작을 방지할 수 있습니다.:

<Select
  dropdownRender={() => (
    <div
      onMouseDown={(e) => {
        e.preventDefault();
        e.stopPropagation();
      }}
    >
      Some Content
    </div>
  )}
/>

왜 커스텀(사용자 정의) 옵션을 사용할 때 스크롤이 깨질 때가 있나요?

가상 스크롤을 각 항목의 높이를 기본적으로 24px로 설정합니다. 옵션의 높이가 다를 경우, listItemHeight와 listHeight를 조정하여 리스트 컨테이너의 높이를 설정해야 합니다.:

<Select listItemHeight={10} listHeight={250} />

참고: listItemHeight와 listHeight는 내부 속성입니다. 꼭 필요할 때만 수정하세요.

왜 a11y 테스트 보고서에서 `aria-` 속성이 누락되나요?

Select는 조작 중일 때만 접근성을 위한 보조 노드를 생성합니다. Select를 열고 다시 시도해보세요. aria-label 및 aria-labelledby 경고가 발생할 경우, 필요한 속성을 사용자의 요구에 맞게 Select에 추가하세요.

기본 가상 스크롤링은 접근성 바인딩을 시뮬레이션하기 위한 모의 요소를 생성합니다. 스크린 리더가 전체 목록에 완전히 접근해야 할 경우, virtual={false}로 설정하여 가상 스크롤링을 비활성화하면 접근성 옵션이 실제 요소에 바인딩됩니다.

기본 사용법

크기

선택 필드의 입력 높이는 기본적으로 32px입니다. size가 large로 설정되면 높이는 40px, small로 설정되면 24px입니다.

정렬 검색

정렬을 통해 옵션을 검색합니다.

그룹 항목

OptGroup을 사용하여 옵션을 그룹화합니다.

자동 토큰화

Lucy, Jack을 복사하여 입력에 붙여넣습니다. 태그와 다중 모드로만 사용할 수 있습니다.

접미사

접미사 아이콘

선택 항목 숨기기

이미 선택된 드롭다운 옵션을 숨깁니다.

디버그 항목 표시

사용자 정의 선택된 레이블 렌더링

현재 선택한 레이블을 사용자 지정 렌더링 할 수 있으며, 이 레이블은 값 백필(backfill)에 사용할 수 있지만 해당 옵션이 누락되어 값을 직접 렌더링하지는 않습니다.

빅데이터

성능이 향상되는 가상스크롤 사용을 선택하고 virtual={false}을 설정하여 끄십시오.

배치

placement를 통해 팝업의 위치를 수동으로 지정할 수 있습니다.

디버그 용법

옵션 레이블이 중앙 정렬됨.

확장된 상태에서 옵션을 검색합니다.

기존 항목에서 다중 선택.

optionRender를 사용하여 드롭다운 옵션의 렌더링을 커스터마이즈 할 수 있습니다.

100000 Items

a10

c12

topLefttopRightbottomLeftbottomRight

HangZhou #310000

233

Lucy

AntDesign

long, long, long piece of text

Select a option

normal

Select a option

Please select

a10

c12

a10

c12

a10

c12

a10

c12

a10

c12

Select a person

a10

c12

a10

c12

China

Tags Mode

Zhejiang

Hangzhou

Lucy (101)

Select users

custom dropdown render

Outlined

Lucy

Filled

Lucy

Borderless

Lucy

gold

cyan

Select Item...

TLTRBLBR

Lucy

Ava Swift

Select

Select

사용 시기

버전 5.11.0 이후 사용 방식 업그레이드

사용 예시

API

Select props

Select Methods

Option props

OptGroup props

Design Token

컴포넌트 토큰어떻게 사용하나요?

글로벌 토큰어떻게 사용하나요?

FAQ

왜 tags 모드에서 검색 시 동일합 옵션이 2개씩 나타날 때가 있나요?

dropdownRender에서 요소를 클릭했을 때 드롭다운이 닫히지 않는 이유는 무엇인가요?

dropdownRender안에서 클릭해도 드롭다운이 닫히지 않도록 하려면 어떻게 하나요?

왜 커스텀(사용자 정의) 옵션을 사용할 때 스크롤이 깨질 때가 있나요?

왜 a11y 테스트 보고서에서 aria- 속성이 누락되나요?

사용 시기

버전 5.11.0 이후 사용 방식 업그레이드

사용 예시

API

Select props

Select Methods

Option props

OptGroup props

Design Token

컴포넌트 토큰어떻게 사용하나요?

글로벌 토큰어떻게 사용하나요?

FAQ

왜 tags 모드에서 검색 시 동일합 옵션이 2개씩 나타날 때가 있나요?

dropdownRender에서 요소를 클릭했을 때 드롭다운이 닫히지 않는 이유는 무엇인가요?

dropdownRender안에서 클릭해도 드롭다운이 닫히지 않도록 하려면 어떻게 하나요?

왜 커스텀(사용자 정의) 옵션을 사용할 때 스크롤이 깨질 때가 있나요?

왜 a11y 테스트 보고서에서 aria- 속성이 누락되나요?

100000 Items

왜 `tags` 모드에서 검색 시 동일합 옵션이 2개씩 나타날 때가 있나요?

`dropdownRender`에서 요소를 클릭했을 때 드롭다운이 닫히지 않는 이유는 무엇인가요?

`dropdownRender`안에서 클릭해도 드롭다운이 닫히지 않도록 하려면 어떻게 하나요?

왜 a11y 테스트 보고서에서 `aria-` 속성이 누락되나요?

왜 `tags` 모드에서 검색 시 동일합 옵션이 2개씩 나타날 때가 있나요?

`dropdownRender`에서 요소를 클릭했을 때 드롭다운이 닫히지 않는 이유는 무엇인가요?

`dropdownRender`안에서 클릭해도 드롭다운이 닫히지 않도록 하려면 어떻게 하나요?

왜 a11y 테스트 보고서에서 `aria-` 속성이 누락되나요?