Tooltip

키보드 포커스나 마우스 올림으로 짧은 도움말을 표시합니다.

용법

포커스 마우스 올림

마우스를 올렸을 때와 키보드 포커스를 받았을 때 같은 도움말을 표시합니다.

<!-- Tooltip / Focus Hover -->
<script setup lang="ts">
import { TooltipRoot, TooltipTrigger, TooltipContent, TooltipArrow } from '@sectile/vue/tooltip'
</script>

<template>
  <TooltipRoot side="top">
    <TooltipTrigger>Hover or focus</TooltipTrigger>
    <TooltipContent>
      <TooltipArrow />
      Keyboard shortcut: ⌘K
    </TooltipContent>
  </TooltipRoot>
</template>

처음부터 열림 상태

처음부터 열린 도움말을 실행 요소 주변에 겹쳐 표시합니다.

<!-- Tooltip / Initially Open -->
<script setup lang="ts">
import { TooltipRoot, TooltipTrigger, TooltipContent, TooltipArrow } from '@sectile/vue/tooltip'
</script>

<template>
  <TooltipRoot side="top">
    <TooltipTrigger>Hover or focus</TooltipTrigger>
    <TooltipContent>
      <TooltipArrow />
      Keyboard shortcut: ⌘K
    </TooltipContent>
  </TooltipRoot>
</template>

외부 상태 관리

현재 값은 부모가 관리하고, 허용된 변경을 컴포넌트에 다시 전달합니다.

<!-- Tooltip / Controlled -->
<script setup lang="ts">
import { TooltipRoot, TooltipTrigger, TooltipContent, TooltipArrow } from '@sectile/vue/tooltip'
</script>

<template>
  <TooltipRoot side="top">
    <TooltipTrigger>Hover or focus</TooltipTrigger>
    <TooltipContent>
      <TooltipArrow />
      Keyboard shortcut: ⌘K
    </TooltipContent>
  </TooltipRoot>
</template>

Floating 위치

이 컴포넌트는 공통 위치 엔진을 사용합니다. 실시간 위치 예시에서 side, align, 간격, 충돌 경계, strategy, tracking을 바꾸며 계산 결과를 확인할 수 있습니다.

API

Vue 패키지: @sectile/vue/tooltip

컴포넌트

TooltipRoot
TooltipTrigger
TooltipPortal
TooltipContent
TooltipArrow

Props

`TooltipRootProps`

align: 타입PositionAlign기본값'center'
기준 요소를 중심으로 팝업 내용을 정렬할 위치입니다.
arrowPadding: 타입number기본값8
화살표와 팝업 가장자리 사이에 둘 최소 간격입니다.
avoidCollisions: 타입boolean기본값true
팝업이 화면 안에 남도록 위치를 뒤집거나 이동할지 여부입니다.
collisionBoundary: 타입PositionBoundary기본값undefined
팝업을 화면 안에 유지할 때 사용할 경계입니다.
collisionPadding: 타입PositionPadding기본값8
팝업과 충돌 경계 사이에 둘 간격입니다.
defaultOpen: 타입boolean기본값false
컴포넌트가 관리하는 초기 열림 상태입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
hideWhenDetached: 타입boolean기본값false
기준 요소가 레이아웃에서 벗어나면 팝업을 숨길지 여부입니다.
open: 타입boolean기본값undefined
연결된 팝업이나 펼침 영역이 열려 있는지 여부입니다.
position: 타입boolean기본값undefined
실행 요소를 기준으로 팝업 위치를 계산할지 여부입니다.
side: 타입PositionSide기본값'bottom'
기준 요소를 중심으로 팝업을 우선 배치할 방향입니다.
sideOffset: 타입number기본값8
팝업과 기준 요소 사이 거리입니다.
strategy: 타입PositionStrategy기본값'absolute'
기준 요소에 연결된 콘텐츠의 CSS 위치 전략입니다.
tracking: 타입PositionTracking기본값undefined
기준 요소에 연결된 콘텐츠가 열린 동안 위치를 갱신할 방식입니다.
unmountOnExit: 타입boolean기본값false
닫힘 모션이 끝난 뒤 presence 관리 콘텐츠를 DOM에서 제거할지 여부입니다.

`TooltipPartProps`

as: 타입PrimitiveAs기본값파트별로 다름
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

`TooltipPortalProps`

defer: 타입boolean기본값false
Teleport 대상을 현재 mount 또는 update tick이 끝날 때 찾을지 여부입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
to: 타입string | HTMLElement기본값'body'
포털 콘텐츠를 옮길 대상입니다.

슬롯

`TooltipRootSlotProps`

disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
open: 타입boolean
연결된 팝업이나 펼침 영역이 열려 있는지 여부입니다.

기타 타입

`TooltipOpenChangeHandler`

type TooltipOpenChangeHandler = PopupFactoryOptions['onOpenChange']

파트

공통 범위: [data-scope="tooltip"]. 컴포넌트 내부로 스타일을 제한할 때 파트 선택자와 함께 사용합니다.

파트	선택자	역할	추가 속성
`trigger`	`[data-part="trigger"]`	연결된 콘텐츠를 열고 닫거나 활성화합니다.	—
`content`	`[data-part="content"]`	현재 상태에 맞는 컴포넌트 콘텐츠를 담습니다.	—
`arrow`	`[data-part="arrow"]`	떠 있는 콘텐츠와 기준점을 시각적으로 연결합니다.	—

키보드 동작

키	동작
`Tab`	실행 요소가 키보드 포커스를 받으면 도움말을 표시합니다.
`Escape`	표시된 도움말을 닫습니다.

접근성

도움말을 실행 요소의 설명으로 연결하고 포커스는 실행 요소에 유지합니다.

관련 WAI-ARIA 패턴에서 호스트 접근성 규칙을 확인할 수 있습니다.

Tooltip ​

용법 ​

포커스 마우스 올림 ​

처음부터 열림 상태 ​

외부 상태 관리 ​

Floating 위치 ​

API ​

Props ​

TooltipRootProps ​

TooltipPartProps ​

TooltipPortalProps ​

슬롯 ​

TooltipRootSlotProps ​

기타 타입 ​

TooltipOpenChangeHandler ​

파트 ​

키보드 동작 ​

접근성 ​

용법