Tooltip

마우스를 올리거나 키보드로 포커스를 주면 뜨는 짧은 글이에요. 아이콘만 있는 버튼의 이름, 단축키, 잘려서 다 보이지 않는 값처럼 화면에 늘 적어 둘 수 없는 설명에 써요. 안에 누를 것이 있으면 Popover를 써요.

사용 예시

아이콘만 있는 버튼

아이콘만으로는 무슨 버튼인지 알기 어려울 때 써요.

tsx

<Tooltip>  <TooltipTrigger render={<Button color="neutral" emphasis="ghost" shape="square" aria-label="보관" />}>    <Archive />  </TooltipTrigger>  <TooltipContent>보관</TooltipContent></Tooltip>

tsx

<Tooltip>  <TooltipTrigger    render={(      <Button        color="neutral"        emphasis="ghost"        shape="square"        aria-label="보관"      />    )}  >    <Archive />  </TooltipTrigger>  <TooltipContent>보관</TooltipContent></Tooltip>

권장

버튼 이름은 aria-label로 주고, Tooltip은 설명으로만 써요.

tsx

<Tooltip>  <TooltipTrigger    render={(      <Button        color="neutral"        emphasis="ghost"        shape="square"      />    )}  >    <Archive />  </TooltipTrigger>  <TooltipContent>보관</TooltipContent></Tooltip>

지양

Tooltip 글은 버튼의 이름이 되지 않아요. 열려 있는 동안에만 설명으로 연결되고, 닫히면 버튼에 이름도 설명도 없어요.

단축키를 함께 보이기

단축키가 있는 동작은 이름 뒤에 Kbd로 적어요.

tsx

<Tooltip>  <TooltipTrigger render={<Button color="neutral" emphasis="ghost" shape="square" aria-label="보관" />}>    <Archive />  </TooltipTrigger>  <TooltipContent>보관 <Kbd>Ctrl</Kbd> <Kbd>E</Kbd></TooltipContent></Tooltip>

잘린 값의 전체 보이기

좁은 곳에서 값이 잘릴 수 있을 때 써요. 값이 잘리지 않았을 때도 Tooltip이 나타나요.

tsx

<Tooltip>  <TooltipTrigger render={<Button color="neutral" emphasis="ghost" size="sm" className="max-w-40" />}>    <span className="truncate">2026년 상반기 브랜드 리뉴얼 회고</span>  </TooltipTrigger>  <TooltipContent>2026년 상반기 브랜드 리뉴얼 회고</TooltipContent></Tooltip>

권장

버튼에는 Tab 키로 포커스가 이동해서 키보드로도 Tooltip을 볼 수 있어요.

2026년 상반기 브랜드 리뉴얼 회고

지양

span처럼 포커스가 이동하지 않는 요소에 쓰면 마우스를 올릴 때만 나타나요. 키보드만 쓰는 사람은 볼 수 없어요.

좁은 세로 막대

버튼을 세로로 배치할 때 써요. side를 right로 두면 TooltipContent가 위아래 버튼을 가리지 않아요.

tsx

<Tooltip>  <TooltipTrigger render={<Button color="neutral" emphasis="ghost" shape="square" aria-label="보관" />}>    <Archive />  </TooltipTrigger>  <TooltipContent side="right">보관</TooltipContent></Tooltip>

저장할 이름

32자를 넘으면 잘려요.

권장

꼭 알아야 하는 내용은 FieldHelp로 화면에 적어요. 터치 화면에서도 보여요.

저장할 이름

지양

터치 화면에서는 버튼을 눌러도 Tooltip이 열리지 않아요.

코드로 열기

마우스를 올리거나 포커스를 주지 않아도 Tooltip을 열어야 할 때 써요. 같은 TooltipProvider 안에서는 하나가 열리면 나머지가 닫혀서, 함께 열어 둘 Tooltip은 각각 TooltipProvider로 감싸요.

tsx

<TooltipProvider>  <Tooltip open={open} onOpenChange={setOpen}>    <TooltipTrigger render={<Button color="neutral" emphasis="outline" />}>보관</TooltipTrigger>    <TooltipContent>목록에서 숨겨요</TooltipContent>  </Tooltip></TooltipProvider>

권장

Tooltip 안에는 글자만 써요.

지양

Tooltip 안으로는 포커스가 이동하지 않아서 키보드로 안의 버튼을 누를 수 없어요.

컨트롤

delay

side

arrow

tsx

<Tooltip>  <TooltipTrigger render={<Button color="neutral" emphasis="outline" />}>보관</TooltipTrigger>  <TooltipContent>목록에서 숨겨요</TooltipContent></Tooltip>

명세

이름
이름	값	기본
Tooltip
open	boolean	-
호출하는 쪽에서 열림 상태를 관리해요. open만 넘기면 마우스와 포커스에 반응하지 않아요.
defaultOpen	boolean	false
처음에 열어 둘지 정해요.
onOpenChange	(open: boolean, eventDetails) => void	-
열리거나 닫히면 호출돼요.
className	string	-
TooltipTrigger와 TooltipContent에 쓸 수 있어요.
render	ReactElement	-
기본 요소 대신 그릴 요소예요. TooltipTrigger에 Button을 넘길 때 써요.
TooltipTrigger
delay	number	-
이 Tooltip만 TooltipProvider와 다른 시간으로 열 때 써요.
TooltipContent
side	top, right, bottom, left	top
그쪽에 공간이 없으면 반대쪽에 떠요.
arrow	boolean	true
트리거를 가리키는 화살표를 보여요.
sideOffset	number, 함수	11, arrow가 없으면 6
기준과 떨어진 거리예요. 단위는 px이에요.
alignOffset	number, 함수	0
align 방향으로 옮기는 거리예요. 단위는 px이에요.
collisionAvoidance	object	-
화면 가장자리에 닿을 때 뒤집을지, 밀어 넣을지 정해요. Base UI Positioner의 값을 그대로 받아요.
TooltipProvider
delay	number	100
마우스를 올린 뒤 나타나기까지의 밀리초예요. 포커스로는 바로 나타나요.