Project Information

Tooltip

hover와 focus 기준의 Tooltip 컴포넌트를 placement, controlled open, disabled usage 중심으로 정리한 가이드 페이지입니다.

Tooltip

Tooltip / usage

Tooltip은 hover와 focus를 기준으로 보조 설명을 보여주는 non-modal helper UI입니다. 기본 사용은 간단하게 유지하고, 필요할 때만 open과 onOpenChange로 외부 제어를 연결합니다.

Prop

ReactNode

Tooltip은 trigger 역할의 children과 표시할 content를 함께 받습니다. 기본 동작은 hover와 focus로 열리고, 마우스가 벗어나거나 blur 되면 닫힙니다.

Prop

default: topCenter

배치는 trigger 기준으로 위/아래와 정렬 위치를 조합해서 지정합니다. 아래 예시는 스타일 확인을 위해 open 상태로 고정해 둔 예시입니다.

Prop

boolean | (nextOpen: boolean) => void

기본적으로는 내부 상태로 열리고 닫히지만, open과 onOpenChange를 주면 외부 상태로도 제어할 수 있습니다. disabled가 true면 툴팁은 열리지 않습니다.

Props Table

Tooltip의 배치, 제어 방식, 비활성화 규칙을 표로 정리했습니다.

Prop	Type	Default	Required	Description
`children`	`ReactNode`	-	Required	tooltip trigger 역할을 하는 콘텐츠입니다. 보통 focus 가능한 버튼/링크/폼 요소를 넣습니다.
`content`	`ReactNode`	-	Required	툴팁 bubble 안에 표시할 설명 콘텐츠입니다.
`placement`	`"topCenter" \| "topLeft" \| "topRight" \| "bottomCenter" \| "bottomLeft" \| "bottomRight"`	`"topCenter"`	Optional	trigger 기준 배치를 지정합니다. 위/아래 방향에 따라 진입 애니메이션 offset도 함께 바뀝니다.
`open`	`boolean`	`undefined`	Optional	주면 controlled 모드로 동작합니다. 내부 hover/focus 이벤트는 onOpenChange만 호출하고 실제 열림 상태는 외부 값이 결정합니다.
`defaultOpen`	`boolean`	`false`	Optional	uncontrolled 모드에서 초기 열림 상태입니다.
`onOpenChange`	`(nextOpen: boolean) => void`	`undefined`	Optional	hover, leave, focus, blur, Escape로 열림 상태가 바뀔 때 호출됩니다.
`disabled`	`boolean`	`false`	Optional	true면 tooltip은 강제로 닫히고, hover/focus로 다시 열리지 않습니다.
`className`	`string`	`undefined`	Optional	Tooltip 루트 wrapper에 커스텀 클래스를 추가합니다.

children가 유효한 React element면 현재 aria-describedby를 보존한 채 tooltip id를 병합합니다. tooltip이 닫히면 이 참조도 함께 제거됩니다. 비-element children은 그대로 렌더링됩니다.