BadgeToggle

한눈에#

필 형태로 하나만 켜는 단일 선택 필터 그룹입니다 — RadioGroup과 같은 APG 패턴이지만 시각은 둥근 필(pill)이라 필터 칩 줄에 어울립니다.

사용 시점#

필 줄에서 하나만 켜는 단일 선택 필터면 BadgeToggle — 다중 선택이나 다른 인터랙션 칩은 다른 컴포넌트입니다.

플레이그라운드#

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

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

<BadgeToggle
  aria-label="상태 필터"
  options={[
    { value: 'active', label: '활성' },
    { value: 'pending', label: '대기' },
    { value: 'done', label: '완료' },
  ]}
/>

변형#

showAll이면 value=''인 "전체" 항목이 맨 앞에 합성되고, defaultValue가 없을 때 전체가 초기 선택됩니다. allLabel로 라벨을 바꿀 수 있습니다.

크기#

단일 크기입니다 — 시각 32px 필(space.8)에 radius.full이고, 히트 영역은 모든 방향으로 확장돼 44px 터치 타깃을 채웁니다. 라벨이 길어도 줄바꿈 없이 가로로 늘어나며, 그룹은 폭이 부족하면 다음 줄로 래핑됩니다.

상태#

• Default — color.surface-muted 배경 + color.text-muted 잉크
• Hover (미선택) — color.surface-hover 배경 + color.text
• Focus — :focus-visible에 color.focus-ring 2px 아웃라인
• 선택(aria-checked) — color.primary-subtle 배경 + color.primary 보더 + color.primary-text 잉크
• Disabled — color.disabled-bg / color.disabled-fg + 커서 차단

Props#

BadgeToggleOption:

접근성#

그룹이 role="radiogroup"(이름은 aria-label 필수), 각 항목이 button[role="radio"] + aria-checked입니다. roving tabindex로 선택된 항목(없으면 첫 활성 항목)만 tabIndex=0이 되어 그룹 진입 후 화살표로 이동합니다.

비활성 항목은 네이티브 disabled로 포커스·선택·키보드 이동에서 모두 제외됩니다.

토큰#

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