MultiSelect

한눈에#

다중 선택 콤보박스 — 칩 트리거 + aria-multiselectable 리스트박스. 선택값은 트리거 안에 제거 버튼이 달린 칩으로 요약됩니다.

사용 시점#

여러 값을 골라 칩으로 요약하면 MultiSelect — 그 외에는 목적에 맞는 컴포넌트를 가리킵니다.

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

import { MultiSelect } from '@wds/ui-web';

<MultiSelect
  aria-label="담당 에이전트"
  options={[
    { value: 'frontend', label: '프론트엔드' },
    { value: 'backend', label: '백엔드' },
    { value: 'mobile', label: '모바일' },
    { value: 'data', label: '데이터' },
  ]}
/>

변형#

showAll이면 목록 맨 위에 "전체" 토글 행이 생기고, 전체가 선택되면 트리거에 칩 나열 대신 전체 1개가 표시됩니다(그 칩의 ×는 전체 해제).

열리면 포커스가 검색 입력으로 이동합니다. 검색 중에는 "전체" 행이 숨겨집니다 — 필터된 부분집합에 대한 전체 토글은 의미가 모호하기 때문입니다.

그룹 일부만 선택되면 헤더 체크박스가 부분 선택(−)으로 표시됩니다. 비활성 옵션은 전체/그룹 토글에서도 제외됩니다.

크기#

단일 크기입니다 — 트리거는 input.height(44px)를 최소 높이로 칩이 줄바꿈되면 늘어나고, 최소 폭 16rem입니다. 리스트는 최대 16rem 높이에서 스크롤됩니다.

상태#

• Focus — 트리거 :focus-visible에 input.border-focus 보더 + 18% 링
• 활성 행 — color.surface-hover 배경(마우스 호버도 활성을 따라감), 활성+선택 행은 color.surface-selected
• 선택 행 — aria-selected + color.primary-text 잉크 + 체크 표시
• Loading — 목록 대신 Spinner / 빈 결과 — emptyText(role="status")
• Disabled — input.bg-disabled 배경 + 포커스·토글 차단

모바일#

DK 모바일 재활용 표준입니다 — mobile을 켜면 팝업 대신 BottomSheet 체크리스트가 열립니다. 데스크톱과 달리 임시 선택입니다: 체크를 바꿔도 즉시 확정되지 않고, footer의 확인을 눌러야 onChange가 한 번 발화합니다. 취소·배경 클릭·Escape·핸들 드래그 다운은 임시 선택을 폐기하며, 시트는 열릴 때마다 커밋된 값으로 새로 시작합니다. searchable·showAll·groupSelectable은 시트 안에서도 동일하게 동작합니다. 라이브 데모는 데스크톱 뷰포트라 코드로 안내합니다.

<MultiSelect
  mobile
  mobileTitle="에이전트 선택"
  confirmLabel="적용"
  searchable
  showAll
  options={agentOptions}
  onChange={(values) => applyAgents(values)}
/>

Props#

MultiSelectOption:

접근성#

트리거가 role="combobox" + aria-haspopup="listbox"(mobile은 "dialog")인 div입니다 — 칩 제거 버튼이 트리거 안에 살기 때문에 중첩 버튼을 피해 div + tabIndex=0으로 구현됩니다. 팝업은 ul[role="listbox"] + aria-multiselectable="true"이고, 포커스는 트리거(searchable이면 검색 입력)에 머물며 aria-activedescendant가 활성 행 id를 가리킵니다.

• 행 선택 상태는 aria-selected, 부분 선택(전체/그룹)은 data-indeterminate — 시각 체크박스는 aria-hidden
• 비활성 옵션은 aria-disabled로 보고되고 클릭·키보드 토글이 차단됩니다
• 외부 클릭으로 닫히며, 옵션 클릭은 mousedown 기본 동작 차단으로 트리거/검색 입력 포커스를 유지합니다
• 뷰포트 하단 공간이 부족하면 팝업이 위로 플립됩니다 (Select 패턴)

토큰#

component 토큰 없이 Input·Checkbox의 component 토큰과 semantic을 직접 소비합니다(신설 기준 §4 미충족).