Tooltip
A versatile tooltip component that displays helpful information when hovering over or focusing on elements. Supports text content, custom elements, keyboard shortcuts, different trigger methods, and positioning options.
Mobile behavior
On iOS and Android, tooltips managed by the GPUI Base overlay are disabled. Shared components may keep their tooltip configuration, but mobile actions still need visible or accessible labels. Direct GPUI .tooltip() calls, including the basic div() example below, bypass this overlay and are not disabled by this policy. See Mobile for integration guidance.
Import
use gpui_kit::component::tooltip::Tooltip;Usage
Basic Tooltip with Text
// Simple text tooltip
div()
.child("Hover me")
.id("basic-tooltip")
.tooltip(|window, cx| {
Tooltip::new("This is a helpful tooltip").build(window, cx)
})Button with Tooltip
Button::new("save-btn")
.label("Save")
.tooltip("Save the current document")Tooltip with Action/Keybinding
actions!(my_actions, [SaveDocument]);
Button::new("save-btn")
.label("Save")
.tooltip_with_action(
"Save the current document",
&SaveDocument,
Some("MyContext")
)Custom Element Tooltip
div()
.child("Hover for rich content")
.id("rich-tooltip")
.tooltip(|window, cx| {
Tooltip::element(|_, cx| {
h_flex()
.gap_x_1()
.child(IconName::Info)
.child(
div()
.child("Muted Text")
.text_color(cx.theme().muted_foreground)
)
.child(
div()
.child("Danger Text")
.text_color(cx.theme().danger)
)
.child(IconName::ArrowUp)
})
.build(window, cx)
})Tooltip with Manual Keybinding
div()
.child("Custom keybinding")
.id("custom-kb")
.tooltip(|window, cx| {
Tooltip::new("Delete item")
.key_binding(Some(Kbd::new("Delete")))
.build(window, cx)
})Advanced Usage
Components with Built-in Tooltip Support
Many components have built-in tooltip methods:
// Button
Button::new("btn")
.label("Click me")
.tooltip("This button performs an action")
// Switch
Switch::new("toggle")
.label("Enable notifications")
.tooltip("Toggle push notifications on/off")
// Checkbox
Checkbox::new("check")
.label("Remember me")
.tooltip("Keep me logged in for 30 days")
// Radio
Radio::new("option")
.label("Option 1")
.tooltip("Select this option to enable feature X")Complex Tooltip Content
div()
.child("Hover for details")
.id("complex-tooltip")
.tooltip(|window, cx| {
Tooltip::element(|_, cx| {
v_flex()
.gap_2()
.child(
h_flex()
.gap_1()
.child(IconName::User)
.child("User Information")
.text_sm()
.font_semibold()
)
.child(
div()
.child("Last login: 2 hours ago")
.text_xs()
.text_color(cx.theme().muted_foreground)
)
.child(
div()
.child("Status: Active")
.text_xs()
.text_color(cx.theme().success)
)
})
.build(window, cx)
})Tooltip in Form Elements
v_flex()
.gap_4()
.child(
Input::new("email")
.placeholder("Enter your email")
.tooltip("We'll never share your email address")
)
.child(
Input::new("password")
.input_type(InputType::Password)
.placeholder("Password")
.tooltip("Must be at least 8 characters with special characters")
)API Reference
Tooltip
| Method | Description |
|---|---|
new(text) |
Create a tooltip with text content |
element(builder) |
Create a tooltip with custom element content |
action(action, context) |
Set action to display keybinding information |
key_binding(kbd) |
Set manual keybinding information |
build(window, cx) |
Build and return the tooltip as AnyView |
Built-in Tooltip Methods
Components with tooltip support typically provide these methods:
| Method | Description |
|---|---|
tooltip(text) |
Add simple text tooltip |
tooltip_with_action(text, action, context) |
Add tooltip with action keybinding |
tooltip(closure) |
Add custom tooltip with builder closure |
Tooltip Styling
The tooltip automatically applies theme-appropriate styling:
- Background:
theme.popover - Text color:
theme.popover_foreground - Border:
theme.border - Shadow: Medium drop shadow
- Border radius: 6px
- Font: System UI font
You can apply additional styling using the Styled trait:
Tooltip::new("Custom styled tooltip")
.bg(cx.theme().accent)
.text_color(cx.theme().accent_foreground)
.build(window, cx)Examples
Toolbar with Tooltips
h_flex()
.gap_1()
.child(
Button::new("new")
.icon(IconName::Plus)
.tooltip_with_action("Create new file", &NewFile, Some("Editor"))
)
.child(
Button::new("open")
.icon(IconName::FolderOpen)
.tooltip_with_action("Open file", &OpenFile, Some("Editor"))
)
.child(
Button::new("save")
.icon(IconName::Save)
.tooltip_with_action("Save file", &SaveFile, Some("Editor"))
)Status Indicators with Tooltips
h_flex()
.gap_2()
.child(
div()
.size_3()
.rounded_full()
.bg(cx.theme().success)
.tooltip(|window, cx| {
Tooltip::new("Connected to server").build(window, cx)
})
)
.child(
div()
.size_3()
.rounded_full()
.bg(cx.theme().warning)
.tooltip(|window, cx| {
Tooltip::new("Limited connectivity").build(window, cx)
})
)Interactive Elements with Rich Tooltips
v_flex()
.gap_3()
.child(
div()
.p_2()
.border_1()
.border_color(cx.theme().border)
.rounded(cx.theme().radius)
.child("File: document.txt")
.id("file-item")
.tooltip(|window, cx| {
Tooltip::element(|_, cx| {
v_flex()
.gap_1()
.child(
h_flex()
.gap_2()
.child(IconName::File)
.child("document.txt")
.text_sm()
.font_medium()
)
.child(
div()
.child("Size: 2.4 KB")
.text_xs()
.text_color(cx.theme().muted_foreground)
)
.child(
div()
.child("Modified: 2 hours ago")
.text_xs()
.text_color(cx.theme().muted_foreground)
)
.child(
h_flex()
.gap_1()
.child(Kbd::new("Enter"))
.child("to open")
.text_xs()
.text_color(cx.theme().muted_foreground)
)
})
.build(window, cx)
})
)Form Validation with Tooltips
struct FormView {
email_error: Option<String>,
password_error: Option<String>,
}
v_flex()
.gap_4()
.child(
Input::new("email")
.placeholder("Email address")
.when_some(self.email_error.clone(), |this, error| {
this.tooltip(move |window, cx| {
Tooltip::element(|_, cx| {
h_flex()
.gap_1()
.child(IconName::AlertCircle)
.child(error.clone())
.text_color(cx.theme().destructive)
})
.build(window, cx)
})
})
)Best Practices
Content Guidelines
- Be concise: Keep tooltip text short and to the point
- Be helpful: Provide additional context, not redundant information
- Use proper tone: Match your application's voice and tone
- Avoid critical info: Don't put essential information only in tooltips
Usage Guidelines
- Progressive disclosure: Use tooltips for additional context, not primary information
- Consistency: Use consistent tooltip patterns throughout your application
- Performance: Avoid complex content in frequently triggered tooltips
- Testing: Test tooltips with both mouse and keyboard interaction
Examples of Good Tooltip Content
// Good: Provides helpful context
Button::new("delete")
.icon(IconName::Trash)
.tooltip("Delete this item permanently")
// Good: Explains abbreviation
div()
.child("CPU: 45%")
.tooltip("Central Processing Unit usage")
// Good: Describes action with keybinding
Button::new("undo")
.icon(IconName::Undo)
.tooltip_with_action("Undo last action", &Undo, Some("Editor"))Examples to Avoid
// Avoid: Redundant information
Button::new("save")
.label("Save")
.tooltip("Save") // Doesn't add value
// Avoid: Critical information
Button::new("delete")
.tooltip("This will permanently delete all your files") // Too important for tooltip onlyDocumentation license: original prose and illustrations for which GPUI Kit holds licensing rights are also offered under CC BY 4.0. When copying or adapting, credit GPUI Kit, link the source (https://gpui-kit.com/component/tooltip) and https://creativecommons.org/licenses/by/4.0/, and indicate changes. Code examples and software source use Apache-2.0; third-party material retains its terms; existing Apache-2.0 permissions remain.
Bundled from GPUI Kit. Documentation prose: CC BY 4.0; code examples: Apache-2.0. Changes: documentation links localized, asset URLs made absolute, and this attribution added.