---
title: "Tooltip 컴포넌트 — zenit Zig UI"
description: "컨트롤에 짧은 보충 설명을 제공합니다.네 방향 배치, hover 지연, portal 레이어, 벗어날 때 dismiss가 레이아웃 트리를 건드리지 않습니다."
url: https://zenit.z.express/ko/components/tooltip
language: ko
alternate_en: https://zenit.z.express/components/tooltip.md
alternate_zh: https://zenit.z.express/zh/components/tooltip.md
alternate_es: https://zenit.z.express/es/components/tooltip.md
alternate_ja: https://zenit.z.express/ja/components/tooltip.md
alternate_fr: https://zenit.z.express/fr/components/tooltip.md
alternate_de: https://zenit.z.express/de/components/tooltip.md
project: zenit v0.1.0-alpha (Zig 0.15.2, macOS)
source: https://github.com/version-next/zenit
---

# Tooltip

`ui.widgets.Tooltip`

컨트롤에 짧은 보충 설명을 제공합니다.

[Video](https://zenit.z.express/media/stories/tooltip.mp4?v=64c28daff2)

**BEHAVIOR CONTRACT**

네 방향 배치, hover 지연, portal 레이어, 벗어날 때 dismiss가 레이아웃 트리를 건드리지 않습니다.

**RECORDED INTERACTION**

가상 커서가 Top trigger에 hover하면 말풍선이 실제로 나타납니다.

`examples/storybook/stories.zig:2475`

```zig
// ── Tooltip ──
pub fn buildTooltip(scope: *ui.Scope, cx: *ui.Cx) anyerror!*ui.Node {
    const a = cx.allocator;
    const c = try col(cx, 12);
    try c.appendChild(a, try label(cx, "Hover a button to see the tooltip (4 positions)"));

    // 四个主方向各一个 trigger，间距大些避免弹层重叠。
    const grid = try ui.box(cx, .{ .direction = .row, .gap = 24, .align_items = .center }, .{});
    const positions = [_]struct { p: W.tooltip.TooltipPosition, t: []const u8 }{
        .{ .p = .top, .t = "Top" },
        .{ .p = .bottom, .t = "Bottom" },
        .{ .p = .left, .t = "Left" },
        .{ .p = .right, .t = "Right" },
    };
    inline for (positions) |spec| {
        const tt = try W.Tooltip(.{ .text = spec.t ++ " tooltip", .position = spec.p }).mount(scope, cx);
        try tt.trigger.appendChild(a, try W.Button(.{ .label = spec.t, .variant = .secondary }).mount(scope, cx));
        try grid.appendChild(a, tt.wrapper);
    }
    try c.appendChild(a, grid);
    return c;
}
```

[GitHub에서 소스 보기examples/storybook/stories.zig:2475](https://github.com/version-next/zenit/blob/HEAD/examples/storybook/stories.zig#L2475)

Storybook에 있는 이 story의 원본 코드입니다(zenit 5f9add5+wip 2026-09-30). `W`는 `ui.widgets`이며, `col` / `row` / `label`은 Storybook 내부의 작은 레이아웃 헬퍼입니다.

### TooltipProps

`ui.widgets.Tooltip`

[src/ui/components/tooltip/mod.zig:23](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/tooltip/mod.zig#L23)

```zig
fn Tooltip(props: TooltipProps) TooltipBuilder
```

| 필드 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `text` | `[]const u8` | — | — |
| `position` | `TooltipPosition` `.top` `.top_start` `.top_end` `.bottom` `.bottom_start` `.bottom_end` `.left` `.left_start` `.left_end` `.right` `.right_start` `.right_end` | `.top` | — |
| `offset` | `f32` | `6` | — |
| `open_delay_ms` | `f32` | `200` | hover 后到 tooltip 开始显示的延迟（ms）；期间移开指针则不显示。 |
| `background` | `?Color` | `null` | — |
| `text_color` | `?Color` | `null` | — |
| `font_size` | `f32` | `12` | — |

### TooltipResult

`ui.widgets.Tooltip`

[src/ui/components/tooltip/mod.zig:40](https://github.com/version-next/zenit/blob/HEAD/src/ui/components/tooltip/mod.zig#L40)

| 필드 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `wrapper` | `*Node` | — | — |
| `trigger` | `*Node` | — | — |
| `content` | `*Node` | — | — |