Tooltip

포인터가 잠시 머물면 나타나는 짧은 설명입니다. 아이콘만 있는 컨트롤의 용도를 보충할 때 씁니다.

import { Button, Tooltip } from 'neba';

<Tooltip content="배포 URL 복사">
  <Button variant="outline" startIcon={<LinkIcon />} />
</Tooltip>;

Props

Prop	타입	기본값	설명
content *	ReactNode	—	툴팁이 하는 말. 짧은 구절이어야 합니다. 툴팁은 터치로 닿을 수 없고 안의 무엇도 누를 수 없습니다
children *	ReactElement	—	툴팁이 매달릴 요소 하나. 트리거가 감싸지 않고 이 요소에 병합되므로 레이아웃에 요소가 늘지 않습니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'sm'	판의 타입 스케일과 여백
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'secondary'	색 계열. 툴팁은 언제나 다른 것에 대한 주석이므로 중립이 기본입니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다
side	'top' | 'right' | 'bottom' | 'left'	'top'	트리거의 어느 쪽에 뜨는지. 자리가 없으면 반대쪽으로 넘어갑니다
align	'start' | 'center' | 'end'	'center'	그 변을 따라 놓이는 위치
sideOffset	number	6	트리거와의 거리(px)
delay	number	600	열리기까지 포인터가 머물러야 하는 시간(ms)
closeDelay	number	0	포인터가 떠난 뒤 닫히기까지(ms)
arrow	boolean	true	트리거를 가리키는 작은 쐐기
open	boolean	—	열림 여부. onOpenChange와 함께
defaultOpen	boolean	false	비제어 툴팁의 초기 상태
onOpenChange	(open: boolean) => void	—	열리거나 닫힐 때 호출
disabled	boolean	false	트리거는 그대로 두고 툴팁만 열리지 않게 합니다. 라벨이 잘렸을 때만 뜨는 툴팁 같은 경우

<div>의 native 속성은 popup으로 전달됩니다. color · content · children만 위 표와 이름이 겹쳐 제외됩니다.

trigger는 별도의 box를 만들지 않고 children에 병합되므로 레이아웃에 영향을 주지 않습니다. children은 ref를 받고 props를 펼칠 수 있는 요소 하나여야 합니다. Neba 컴포넌트는 모두 해당합니다.

예시

side와 align

side는 trigger를 기준으로 팝업이 놓일 방향, align은 그 축 위의 정렬입니다. 창 가장자리에 자리가 없으면 반대쪽으로 자동으로 넘어갑니다. sideOffset으로 간격을, arrow로 꼬리표 표시를 조절합니다.

import { Button, Tooltip, type NebaSide } from 'neba';

const SIDES: NebaSide[] = ['top', 'right', 'bottom', 'left'];

export default function TooltipSides() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {SIDES.map((side) => (
        <Tooltip key={side} side={side} delay={0} content={`Placed on the ${side}`}>
          <Button variant="outline" color="secondary">
            {side}
          </Button>
        </Tooltip>
      ))}
    </div>
  );
}

delay와 TooltipProvider

delay는 포인터가 머문 뒤 열릴 때까지의 시간, closeDelay는 벗어난 뒤 닫힐 때까지의 시간입니다.

TooltipProvider로 감싸면 그 안의 Tooltip들이 지연을 공유합니다. 하나가 열린 뒤에는 이웃이 즉시 열리고, 잠시 쉬면 지연이 다시 적용됩니다. 아이콘 버튼이 여러 개 놓인 툴바에서 매번 지연을 기다리지 않게 됩니다.

import { Button, ButtonGroup, Tooltip, TooltipProvider } from 'neba';

function BoldIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M5 3h4a2.5 2.5 0 0 1 0 5H5zm0 5h4.5a2.5 2.5 0 0 1 0 5H5z"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinejoin="round"
      />
    </svg>
  );
}

function ItalicIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M10 3H6.5m3 10H6m3.5-10L7 13"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
      />
    </svg>
  );
}

function UnderlineIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">
      <path
        d="M4.5 3v4.5a3.5 3.5 0 0 0 7 0V3M4 13.5h8"
        stroke="currentColor"
        strokeWidth="1.5"
        strokeLinecap="round"
      />
    </svg>
  );
}

/**
 * One delay shared across the row: once any of these has opened, its
 * neighbours open instantly, and the wait comes back after a pause.
 */
export default function TooltipGrouped() {
  return (
    <TooltipProvider delay={400}>
      <ButtonGroup variant="outline" color="secondary">
        <Tooltip content="Bold">
          <Button startIcon={<BoldIcon />} />
        </Tooltip>
        <Tooltip content="Italic">
          <Button startIcon={<ItalicIcon />} />
        </Tooltip>
        <Tooltip content="Underline">
          <Button startIcon={<UnderlineIcon />} />
        </Tooltip>
      </ButtonGroup>
    </TooltipProvider>
  );
}

접근성

• 팝업에 role="tooltip"이 붙고, 열려 있는 동안에만 trigger에 aria-describedby가 연결됩니다.
• Tooltip은 설명이지 이름이 아닙니다. 아이콘만 있는 버튼에는 aria-label을 따로 주세요.
• 키보드 focus에서는 열리지만 클릭으로 옮겨온 focus에서는 열리지 않습니다. Esc로 닫힙니다.
• 터치 화면에서는 포인터로 닿을 수 없고, 안에 넣은 컨트롤은 누를 수 없습니다. 둘 중 하나가 필요하면 popover를 쓰세요.