Adding Tooltips to SwiftUI Views on macOS

Tooltips are a subtle but powerful way to improve usability on macOS. They give users extra context when they hover over buttons, text, or icons without cluttering the main UI. SwiftUI makes it easy to add tooltips — and also flexible enough to create custom ones when you need more control.

The Default Tooltip: `.help`

The simplest way to add a tooltip in SwiftUI is with the .help(...) modifier. This attaches a native macOS tooltip to any view:

Button("Hover me") {
    print("Clicked")
}
.help("This is a tooltip shown when you hover.")

On macOS, this displays the familiar yellow system tooltip bubble. On iOS, .help instead contributes to accessibility features like VoiceOver.

Multiline Tooltips with `.help`

If you want more than one line of text, you can simply add line breaks:

Button("Hover me") {}
    .help("This is line one.\nThis is line two.")

The system tooltip will wrap and display multiple lines. This covers most basic cases where you just need to explain an action or shortcut.

Custom Tooltips for More Control

Sometimes you need more than plain text: maybe an icon, styled text, or explanatory notes. SwiftUI doesn’t style .help, but you can build your own tooltip using onHover and an overlay.

Here’s a reusable component:

import SwiftUI

struct Tooltip<Content: View>: ViewModifier {
    @State private var isHovering = false
    let tooltipContent: Content
    
    init(@ViewBuilder content: () -> Content) {
        self.tooltipContent = content()
    }
    
    func body(content: ContentOf<Self>) -> some View {
        content
            .onHover { hovering in
                withAnimation(.easeInOut(duration: 0.2)) {
                    isHovering = hovering
                }
            }
            .overlay(alignment: .top) {
                if isHovering {
                    tooltipContent
                        .padding(8)
                        .background(
                            RoundedRectangle(cornerRadius: 6)
                                .fill(Color(.windowBackgroundColor))
                        )
                        .overlay(
                            RoundedRectangle(cornerRadius: 6)
                                .stroke(Color.gray.opacity(0.2))
                        )
                        .shadow(radius: 3)
                        .offset(y: -40)
                        .transition(.opacity.combined(with: .scale))
                }
            }
    }
}

extension View {
    func tooltip<Content: View>(@ViewBuilder _ content: () -> Content) -> some View {
        self.modifier(Tooltip(content: content))
    }
}

And here’s how you use it:

Image(systemName: "star.fill")
    .resizable()
    .frame(width: 40, height: 40)
    .foregroundStyle(.yellow)
    .tooltip {
        VStack(alignment: .leading) {
            Text("Favorites")
                .font(.headline)
            Text("Mark this item as a favorite to access it quickly.")
                .font(.caption)
                .foregroundColor(.secondary)
        }
    }

Now you have full control over your tooltip’s design: multiple text styles, icons, even custom layouts.

Wrapping Up

Use .help for the default macOS tooltip — it’s native, accessible, and quick.
Add \n for multiline content if you just need more space.
Build a custom tooltip with onHover and overlays when you want rich, styled, or interactive hints.

With these three approaches, you can cover everything from simple hints to fully branded helper popups, while still feeling right at home on macOS.