Listbox
Listbox (리스트박스)
선택할 수 있는 옵션 목록을 표시하는 컴포넌트예요. 그룹·다중 선택·가상화·전송 목록 등 다양한 선택 시나리오를 지원해요.
출처: 문서
본문
사용법 (Usage)
import { Listbox } from "@chakra-ui/react"
<Listbox.Root>
<Listbox.Label />
<Listbox.Content>
<Listbox.Item>
<Listbox.ItemText />
<Listbox.ItemIndicator />
</Listbox.Item>
</Listbox.Content>
</Listbox.Root>
리스트박스를 구성하려면 useListCollection을 사용해 리스트 컬렉션을 관리해요.
예제 (Examples)
제어 (Controlled)
커스텀 상태 관리를 위해 value와 onValueChange prop을 사용해 리스트박스 값을 외부에서 제어해요.
스토어와 함께 (With Store)
리스트박스를 제어하는 또 다른 방법은 RootProvider 컴포넌트와 useListbox 스토어 훅을 사용하는 것이에요.
이렇게 하면 리스트박스 외부에서도 상태와 메서드에 접근할 수 있어요.
RootProvider + useListbox또는Root중 하나만 사용하세요.
비활성화된 항목 (Disabled Item)
사용할 수 없는 옵션을 컨텍스트로 남겨두기 위해 보이게 유지하면서 해당 항목을 비활성화해요.
그룹화 (Grouped)
항목 그룹을 사용해 관련 옵션을 명확한 섹션 헤더와 함께 정리해, 사용자가 특정 카테고리를 쉽게 찾을 수 있게 해요.
가로 레이아웃 (Horizontal)
리스트박스 항목을 카드 형태의 가로 레이아웃으로 표시해요. 미디어 갤러리나 시각적 선택 인터페이스에 적합해요.
다중 선택 (Multiple Selection)
사용자가 목록에서 여러 항목을 선택할 수 있게 해요. 태그·카테고리·선호도 선택 같은 시나리오에 유용해요.
전체 선택 (Select All)
다중 선택 시나리오에서 편리한 "Select All"과 "Select None" 컨트롤을 제공하고, 선택 상태를 시각적으로 표시해요.
확장 선택 (Extended Select)
확장 선택 모드를 사용하면 Cmd/Ctrl 같은 키보드 단축키로 여러 항목을 선택할 수 있어요.
체크마크와 함께 (With Checkmark)
다중 선택 시나리오에서 커스텀 체크마크를 표시해 선택된 항목에 대한 명확한 시각적 피드백을 제공해요.
아이콘과 함께 (With Icon)
리스트박스 항목에 아이콘을 추가해 시각적 컨텍스트를 제공하고 옵션 인식을 높여요.
설명과 함께 (With Description)
각 항목에 추가 설명 텍스트를 포함해 더 많은 컨텍스트를 제공하고 사용자가 정보에 기반한 선택을 하도록 도와요.
입력과 함께 (With Input)
리스트박스에 검색 입력을 결합해 옵션을 동적으로 필터링해요. 긴 목록에서 특정 항목을 쉽게 찾을 수 있어요.
키보드 우선순위 (Keyboard Priority)
Listbox.Input에 keyboardPriority="navigate"를 설정하면 Home과 End가 텍스트 커서 대신 강조된 항목을 이동시켜요. 기본 caret 모드는 네이티브 텍스트 편집 동작을 유지해요.
Popover와 함께 (With Popover)
popover 안에서 리스트박스를 사용해, 영구적인 화면 공간을 차지하지 않으면서 다른 콘텐츠 위에 겹쳐지는 드롭다운형 선택 메뉴를 만들어요.
Dialog와 함께 (With Dialog)
모달 다이얼로그에서 리스트박스를 제공해 집중된 선택 경험을 만들어요. 사용자 주의가 필요한 중요한 선택에 특히 유용해요.
가상화 (Virtualized)
가상화로 대용량 데이터셋을 효율적으로 처리해요. 수천 개의 항목에서도 부드러운 스크롤 성능을 유지하기 위해 보이는 항목만 렌더링해요.
이미지 탐색기 (Image Explorer)
리스트박스를 내비게이션으로 사용해 서로 다른 이미지나 미디어 콘텐츠를 표시하는 대화형 갤러리를 만들어요.
전송 목록 (Transfer List)
이중 리스트박스 인터페이스를 만들어 항목을 사용 가능 상태와 선택 상태 사이에서 이동시켜요. 권한 관리나 항목 선택 워크플로에 흔히 사용돼요.
이모지 그리드 (Emoji Grid)
필터링 기능이 있는 그리드 레이아웃에서 이모지를 표시해요. 이모지 피커나 아이콘 선택 인터페이스에 적합해요.
Props
Root
Listbox 컴포넌트의 Root 부분에 대한 prop 테이블 (대화형 문서 참고).
Label
Listbox 컴포넌트의 Label 부분에 대한 prop 테이블 (대화형 문서 참고).
Input
Listbox 컴포넌트의 Input 부분에 대한 prop 테이블 (대화형 문서 참고).
Content
Listbox 컴포넌트의 Content 부분에 대한 prop 테이블 (대화형 문서 참고).
Item
Listbox 컴포넌트의 Item 부분에 대한 prop 테이블 (대화형 문서 참고).
ItemText
Listbox 컴포넌트의 ItemText 부분에 대한 prop 테이블 (대화형 문서 참고).
ItemIndicator
Listbox 컴포넌트의 ItemIndicator 부분에 대한 prop 테이블 (대화형 문서 참고).
ItemGroup
Listbox 컴포넌트의 ItemGroup 부분에 대한 prop 테이블 (대화형 문서 참고).
ItemGroupLabel
Listbox 컴포넌트의 ItemGroupLabel 부분에 대한 prop 테이블 (대화형 문서 참고).