Tooltip

useTooltip이 열림 상태 머신입니다. 트리거에 getTriggerProps를 펼치세요. Tooltip.Root에 getTooltipProps를 펼치세요. Tooltip.Root는 팁 외형만 담당합니다. children, className, style, 그리고 인터랙티브일 때의 다이얼로그 이름입니다. Tooltip.Trigger나 Tooltip.Content는 없습니다. Tooltip.Root에 interactive를 설정하지 마세요.

기본값은 텍스트만 담는 role="tooltip"입니다. 호버는 300ms를 기다립니다. 포커스는 즉시 엽니다. 거친 포인터에서는 포커스만 씁니다.

useTooltip에 interactive: true를 넘기세요. 표면은 비모달 팁 다이얼로그가 됩니다. popover="manual"과 role="dialog"를 씁니다. React Aria의 PreviewTrigger와 Popover도 모달이 아닌 호버 팁에 role="dialog"를 강제합니다. role="tooltip"은 절대 쓰지 않습니다. Tooltip.Root에 aria-label이나 aria-labelledby 중 정확히 하나를 설정하세요. 링크를 넣을 수 있습니다. Tab은 그 링크로 이동합니다. 호버는 패널로 넘어갈 수 있습니다. Escape는 포커스를 트리거로 돌려보내며, 키를 뗄 때까지 다시 열지 않습니다. 포커스 트랩은 없습니다.

배치는 CSS 앵커로 합니다. 팁은 트리거 위에 놓이고, 공간이 부족하면 아래로 뒤집힙니다. 화살표와 배치 prop은 없습니다. 팁은 최상위 레이어에 그려지고 트리거의 transform 적용 전 상자를 기준으로 놓이므로, CSS transform으로 옮긴 요소 안의 트리거에서는 transform이 없을 때 트리거가 있을 자리에 팁이 나타납니다.

예시

오버플로 칩과 버튼이 아닌 다른 트리거는 useTooltip을 씁니다. 이 데모의 코드도 그곳에 있습니다. 탭으로 이동할 수 없는 래퍼에는 tabIndex={0}을 지정하세요.

링크가 있는 인터랙티브 팁입니다. useTooltip에 interactive: true를 설정하세요. 훅이 상태 머신을 맡도록 Button.Root에 tooltip={false}를 설정하세요.

무엇을 어디에 두나요

Button 편의 기능

아이콘만 있는 Button.Root는 접근 가능한 이름을 팁으로 보여 줍니다. aria-label이나 aria-labelledby를 넘기세요. 레이블이 있는 버튼은 레이블이 넘칠 때만 전체 문자열을 팁으로 보여 줍니다. tooltip={false}로 끌 수 있습니다. 레이블이 다 들어가는 버튼은 팁을 보여 주지 않습니다.

언제 쓰나요

언제: 컨트롤에 대한 짧은 힌트(아이콘만 있는 버튼의 이름, 잘린 레이블). Button.Root는 자신의 아이콘 전용 이름이나 잘린 레이블을 직접 팁으로 보여 줍니다. 그 밖의 트리거는 useTooltip + 표면만 담당하는 Tooltip.Root를 씁니다. 기본 팁은 텍스트만 담습니다(role="tooltip").

쓰지 않을 때: 팁 안의 링크 → interactive: true를 준 useTooltip(비모달 팁 다이얼로그, 링크만). 액션 메뉴 → Menu. 그 밖의 액션 → Popover. 긴 도움말 → Description. 모달 작업 → Dialog.

Props

열림 상태 머신의 props는 useTooltip에 있습니다.