ChipList

칩을 maxRows 줄까지 보여 주고 나머지는 +N 버튼으로 접는 목록입니다. +N을 누르면 접힌 칩이 담긴 팝오버가 열립니다. 목록 이름은 aria-label이나 aria-labelledby로 붙이세요.

onRemove를 주면 칩마다 제거 버튼이 생깁니다. 포커스가 있던 칩이 chips에서 빠지면 포커스는 그 자리를 채운 칩으로, 없으면 앞 칩으로, 그것도 없으면 +N으로, 그마저 없으면 목록으로 옮겨 갑니다.

<ChipList.Root
  aria-label="Tags"
  chips={tags}
  maxRows={1}
  onRemove={(index) => setTags((current) => current.filter((_, i) => i !== index))}
/>

팝오버에서 마지막 칩에서 Tab을 누르면 +N 다음 컨트롤로 가고, 첫 칩에서 Shift+Tab을 누르면 +N으로 돌아가며, Escape를 누르면 팝오버가 닫히고 +N으로 돌아갑니다.

한 줄 / 두 줄

designtokensaccessibilitya-very-long-tag-that-stays-putreactdensitydark modedocs

읽기 전용

designtokensaccessibilitya-very-long-tag-that-stays-putreactdensitydark modedocs

언제 쓰나요

언제: 적용된 필터, 읽기 전용 태그, 수신자처럼 텍스트 필드 밖의 칩을 maxRows로 제한하고 +N 개수를 보일 때.

쓰지 않을 때: 새 칩 입력 → Field.ChipInput. 옵션에서 고르기 → Combobox 레시피. 선택하거나 토글하는 칩 → Checkbox / Button.Root. 칩 하나 → Chip.Root. 접기 둘레의 마크업을 직접 만들 때 → useChipList.

Props

ChipList.Root props
이름	타입	필수	기본값	설명
chips	`readonly string[]`	예	—	칩 레이블, 순서대로.
maxRows	`number`	아니요	—	나머지를 +N으로 접기 전에 보여 줄 줄 수. 없으면 모든 칩이 필요한 만큼 줄을 바꿔 놓입니다.
getKey	`(value: string, index: number) => string`	아니요	—	칩마다 고유하고 바뀌지 않는 키. chips가 바뀌어도 포커스가 그 칩을 따라갈 수 있습니다. 없으면 칩을 값으로 맞춰 보므로, 포커스가 같은 값을 가진 다른 칩에 놓일 수 있습니다.
onRemove	`(index: number, value: string) => void`	아니요	—	칩마다 제거 버튼을 렌더링합니다. 포커스가 있던 칩이 chips에서 빠지면, 포커스는 그 자리를 채운 칩으로, 없으면 앞 칩으로, 그것도 없으면 +N으로, 그마저 없으면 목록으로 옮겨 갑니다.
removeLabel	`(value: string) => string`	아니요	—	제거 버튼의 이름. 기본값은 StringsProvider의 removeChip 문자열이며, 영어로는 Remove {value}입니다.
removeIcon	`React.ReactNode`	아니요	—	제거 버튼의 내용. 예: 직접 사용하는 아이콘 세트의 아이콘. 없으면 CSS가 X 모양을 그립니다.
overflowLabel	`(n: number) => string`	아니요	—	+N 버튼의 이름. 기본값은 StringsProvider의 moreChips 문자열이며, 영어로는 {n} more입니다.
panelLabel	`(n: number) => string`	아니요	—	접힌 칩이 담긴 팝오버의 이름. 기본값은 StringsProvider의 moreChipsPanel 문자열이며, 영어로는 {n} more chips(1개일 때 1 more chip)입니다.