Component

Tooltip

마우스 호버나 키보드 포커스 시 추가 정보를 표시하는 툴팁 컴포넌트입니다.

Playground

옵션을 조절하며 화면과 사용 코드를 함께 확인하세요.

PC 1280px

Controls

호버 시 표시 지연 시간 (ms)

연속 호버 시 지연 건너뛰기 (ms)

초기 열림 상태

툴팁 크기

툴팁 표시 위치

툴팁 정렬

트리거와의 간격 (px)

툴팁 제목 텍스트

툴팁 설명 텍스트

Code

import { Tooltip, Button } from '@amineslab/ui'

export default function ExamplePreview() {
  return ((<Tooltip.Provider delayDuration={0} skipDelayDuration={0}>
      <Tooltip key={"false"} defaultOpen={false}>
        <Tooltip.Trigger asChild>
          <Button variant="outline">Hover me</Button>
        </Tooltip.Trigger>
        <Tooltip.Content size={"md"} side={"top"} align={"center"} sideOffset={4}>
          {<Tooltip.Title>{"Title"}</Tooltip.Title>}
          {<Tooltip.Description>{"Description text goes here."}</Tooltip.Description>}
          {false}
        </Tooltip.Content>
      </Tooltip>
    </Tooltip.Provider>))
}

Props

import {
  Tooltip,
  TooltipProvider,
  TooltipTrigger,
  TooltipContent,
  TooltipTitle,
  TooltipDescription,
  TooltipArrow,
} from '@amineslab/ui'

`Tooltip.Provider`

여러 Tooltip에 공통 설정을 제공하는 컨텍스트 프로바이더입니다.

Name	Type	Default	Description
`delayDuration`	`number`	`700`	마우스 호버 시 툴팁이 나타나기까지의 지연 시간 (ms)
`skipDelayDuration`	`number`	`300`	연속 호버 시 지연을 건너뛰는 시간 (ms)

`Tooltip`

개별 툴팁의 루트 컨테이너입니다.

Name	Type	Default	Description
`open`	`boolean`	-	제어 모드에서의 열림 상태
`defaultOpen`	`boolean`	`false`	비제어 모드에서의 초기 열림 상태
`onOpenChange`	`(open: boolean) => void`	-	열림 상태 변경 콜백 함수
`delayDuration`	`number`	-	개별 툴팁의 지연 시간 (Provider 설정 덮어쓰기)

`Tooltip.Trigger`

마우스 호버/포커스로 툴팁을 활성화하는 트리거 요소입니다.

Name	Type	Default	Description
`asChild`	`boolean`	`false`	true일 때 자식 요소를 트리거로 렌더링합니다.

`Tooltip.Content`

툴팁 내용을 표시하는 컨테이너입니다.

Name	Type	Default	Description
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	툴팁 크기입니다. xs는 내용 너비, sm·md·lg·xl는 각각 160·240·320·400px이며 좁은 화면에서는 화면 너비 안으로 제한됩니다.
`side`	`'top' \| 'right' \| 'bottom' \| 'left'`	`'top'`	툴팁 표시 위치
`align`	`'start' \| 'center' \| 'end'`	`'center'`	툴팁 정렬
`sideOffset`	`number`	`4`	트리거와의 간격 (px)
`portalContainer`	`HTMLElement \| null`	-	툴팁 Portal을 마운트할 요소입니다. 생략하면 document.body를 사용합니다.

`Tooltip.Title`

툴팁 제목 텍스트입니다.

HTML <div> 요소의 표준 속성을 그대로 받습니다.

`Tooltip.Description`

툴팁 설명 텍스트입니다.

HTML <div> 요소의 표준 속성을 그대로 받습니다.

Examples

자주 쓰는 조합을 살펴보고, 필요한 예시의 코드를 펼쳐 확인하세요.

Size

다양한 크기의 툴팁을 표시합니다. 버튼에 마우스를 올리거나 키보드로 포커스해 확인하세요.

import { Tooltip, type ControlSize, type TooltipContentProps, Button } from '@amineslab/ui'

function TooltipSample({ label, title, description, ...props }: TooltipContentProps & {
    label: string;
    title?: string;
    description?: string;
}) {
    return (<Tooltip>
      <Tooltip.Trigger asChild>
        <Button variant="outline">{label}</Button>
      </Tooltip.Trigger>
      <Tooltip.Content {...props}>
        {title && <Tooltip.Title>{title}</Tooltip.Title>}
        {description && <Tooltip.Description>{description}</Tooltip.Description>}
        {!title && !description && 'Tooltip'}
      </Tooltip.Content>
    </Tooltip>);
}

const controlSizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const satisfies readonly ControlSize[];

const sizes = controlSizes;

export default function ExamplePreview() {
  return ((<Tooltip.Provider delayDuration={0} skipDelayDuration={0}>
          <div className="flex flex-wrap items-center gap-4">
            {sizes.map((size) => (<TooltipSample key={size} size={size} label={size} title={size === 'xs' ? undefined : 'Title'} description={size === 'xs' ? undefined : `${size} 크기의 툴팁입니다.`}/>))}
          </div>
        </Tooltip.Provider>))
}

Placement

4방향으로 툴팁을 표시합니다. 화면 가장자리에서는 잘리지 않도록 위치가 자동 조정됩니다.

import { Tooltip, type TooltipContentProps, Button } from '@amineslab/ui'

function TooltipSample({ label, title, description, ...props }: TooltipContentProps & {
    label: string;
    title?: string;
    description?: string;
}) {
    return (<Tooltip>
      <Tooltip.Trigger asChild>
        <Button variant="outline">{label}</Button>
      </Tooltip.Trigger>
      <Tooltip.Content {...props}>
        {title && <Tooltip.Title>{title}</Tooltip.Title>}
        {description && <Tooltip.Description>{description}</Tooltip.Description>}
        {!title && !description && 'Tooltip'}
      </Tooltip.Content>
    </Tooltip>);
}

const sides = ['top', 'right', 'bottom', 'left'] as const;

export default function ExamplePreview() {
  return ((<Tooltip.Provider delayDuration={0} skipDelayDuration={0}>
          <div className="flex flex-wrap items-center gap-4">
            {sides.map((side) => (<TooltipSample key={side} label={side} size="xs" side={side} description={side}/>))}
          </div>
        </Tooltip.Provider>))
}

Content Variants

Title과 Description 조합에 따른 콘텐츠 변형입니다.

import { Tooltip, type TooltipContentProps, Button } from '@amineslab/ui'

function TooltipSample({ label, title, description, ...props }: TooltipContentProps & {
    label: string;
    title?: string;
    description?: string;
}) {
    return (<Tooltip>
      <Tooltip.Trigger asChild>
        <Button variant="outline">{label}</Button>
      </Tooltip.Trigger>
      <Tooltip.Content {...props}>
        {title && <Tooltip.Title>{title}</Tooltip.Title>}
        {description && <Tooltip.Description>{description}</Tooltip.Description>}
        {!title && !description && 'Tooltip'}
      </Tooltip.Content>
    </Tooltip>);
}

export default function ExamplePreview() {
  return ((<Tooltip.Provider delayDuration={0} skipDelayDuration={0}>
          <div className="flex flex-wrap items-center gap-4">
            <TooltipSample label="타이틀만" size="md" title="툴팁 타이틀"/>
            <TooltipSample label="설명만" size="md" description="툴팁 설명 텍스트입니다."/>
            <TooltipSample label="타이틀 + 설명" size="md" title="툴팁 타이틀" description="타이틀과 설명이 함께 표시됩니다."/>
          </div>
        </Tooltip.Provider>))
}

사용 기준

권장하는 사용

Provider, Trigger, Content, Title, Description을 조합합니다.
짧은 라벨에는 xs, 제목과 설명에는 sm부터 xl까지 사용합니다.

피해야 할 사용

필수 설명을 Tooltip에만 두거나 내부에 버튼·링크를 넣지 마세요.
터치로 열어야 하는 도움말은 Popover를 사용하세요.

접근성

화면에 맞는 이름을 제공하고, 키보드만으로 작업을 마칠 수 있는지 확인하세요.

이 컴포넌트에는 별도의 키보드 조작이 필요하지 않습니다.