기본 코드 예시
공통 베이스라인
tooltip 역할 사용
툴팁 텍스트를 담은 요소에 role="tooltip"이 있어야 합니다.
aria-describedby로 연결
트리거 요소에 aria-describedby로 툴팁의 id를 연결해야 합니다.
Escape로 닫기
Escape 키로 툴팁을 닫을 수 있어야 하며 포커스는 이동하지 않아야 합니다.
포커스 시 표시
마우스 호버뿐 아니라 키보드 포커스 시에도 툴팁이 표시되어야 합니다.
툴팁 내 포커스 가능 요소 금지
툴팁에는 링크나 버튼 등 인터랙티브 요소를 포함하면 안 됩니다.
툴팁 위 호버 시 유지
WCAG 1.4.13에 따라 포인터가 툴팁 위로 이동해도 툴팁이 유지되어야 합니다.
짧은 지연 후 표시
우발적 트리거를 방지하기 위해 300–500ms 지연 후 표시하세요.
툴팁 내 인터랙티브 요소 금지
버튼, 링크, 폼 컨트롤은 툴팁이 아닌 dialog 패턴을 사용하세요.
HTML title 속성만 사용 금지
title 속성은 키보드 접근성이 없으며 스크린리더마다 동작이 다릅니다.
디자인 시스템별 구현
추가 체크포인트
enterDelay 300ms 이상 설정
enterDelay prop으로 300ms 이상의 지연을 추가해 우발적 표시를 방지하세요. 기본값은 100ms로 너무 짧을 수 있습니다.
아이콘 버튼 트리거에 aria-label 필수
Tooltip의 title은 시각적 설명을 보조하지만 접근 가능한 이름을 대체하지 않습니다. 아이콘만 있는 버튼에는 반드시 aria-label을 제공하세요.
커스텀 children에 forwardRef 구현
Tooltip은 children에 DOM 이벤트 리스너를 주입합니다. 커스텀 컴포넌트를 children으로 사용할 경우 React.forwardRef로 ref를 전달해야 합니다.
코드 샘플
구현 노트
- –MUI Tooltip은 role="tooltip"과 aria-describedby를 자동으로 설정합니다.
- –enterDelay: 툴팁 표시 지연(ms), 기본값 100 — 300 이상 권장.
- –leaveDelay: 툴팁 숨김 지연(ms), 기본값 0.
- –disabled 버튼에 툴팁을 표시하려면 <span>으로 감싸야 합니다. disabled 버튼은 포인터 이벤트를 수신하지 않습니다.
- –커스텀 children 컴포넌트는 React.forwardRef를 구현해야 이벤트 리스너가 올바르게 연결됩니다.