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	트리거는 그대로 두고 툴팁만 열리지 않게 합니다 — 라벨이 잘렸을 때만 뜨는 툴팁 같은 경우

예시

방향

자리가 없으면 반대쪽으로 넘어갑니다. Base UI가 하는 일이고, 옳은 동작입니다 — 창 가장자리에 잘린 툴팁은 반대편에 뜬 툴팁보다 나쁩니다.

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>
  );
}

툴바 하나에 지연 하나

TooltipProvider는 지연을 그룹이 함께 씁니다. 하나가 열리고 나면 이웃들은 즉시 열리고, 잠시 쉬면 다시 기다림이 돌아옵니다. 이것이 없으면 아이콘 버튼 줄을 훑을 때마다 매번 전체 지연을 기다려야 하고, 툴팁이 포인터와 싸우는 것처럼 느껴지는 이유가 바로 그것입니다.

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>
  );
}

감쌀 뿐, 더하지 않습니다

Base UI의 트리거는 자기 박스를 그리는 대신 자식에 병합됩니다. 그래서 툴팁은 레이아웃에 아무 비용도 들이지 않고, 자식은 원래 그것이었던 것 그대로 남습니다 — 버튼이든, 칩이든, 잘린 표 셀이든. 자식은 ref를 받고 props를 펼쳐 주는 요소 하나여야 하는데, Neba 컴포넌트는 모두 그렇습니다.

짧게 쓰세요

툴팁은 그릇이 아닙니다. 터치 화면에서는 포인터로 닿을 수 없고, 주의가 옮겨가는 순간 사라지며, 안에 누를 수 있는 무언가를 넣어도 누를 수 없습니다. 둘 중 하나가 필요한 내용이라면 그것은 popover의 일입니다.

판이 서리 유리가 아니라 채워진 면인 이유도 같습니다. 이 라이브러리에서 떠 있는 다른 모든 것은 반투명 아크릴이지만, 툴팁은 떠 있는 0.5초 동안 하필 그 뒤에 있는 무엇 위에서 읽혀야 하고, 반투명한 시트는 대비를 약속할 수 없는 유일한 표면입니다.

접근성

지연과 그룹 타임아웃, 키보드 포커스에서는 열리되 클릭에서 온 포커스에서는 열리지 않는 처리, Esc로 닫기, 창 가장자리를 피하는 위치 계산은 Base UI가 합니다.

Base UI가 일부러 열어 둔 부분 — 팝업은 여러 가지일 수 있고 어떤 것인지는 호출자만 압니다 — 은 여기서 연결합니다. 판에 role="tooltip"이 붙고, 열려 있는 동안에만 트리거에 그 판을 가리키는 aria-describedby가 붙습니다.

툴팁은 설명이지 이름이 아닙니다. 컨트롤에 이름이 필요하면 이름을 주세요. 아이콘만 있는 버튼에는 aria-label이 필요하고, 그 옆의 툴팁은 덧붙이는 한 문장이지 라벨이 아닙니다.