Tooltip

A lightweight tooltip component that displays contextual hints on hover (macOS) or long press (iOS/iPadOS). Perfect for providing additional context without cluttering the interface.

Import

import PrettyUI

Basic Usage

Attach a tooltip to any view with simple text:

PIconButton("questionmark.circle") {}
    .pTooltip("Click for help")

Placement

Control where the tooltip appears relative to its anchor:

VStack(spacing: 40) {
    PIconButton("arrow.up") {}
        .pTooltip("Top tooltip", placement: .top)
    
    HStack(spacing: 100) {
        PIconButton("arrow.left") {}
            .pTooltip("Leading tooltip", placement: .leading)
        
        PIconButton("arrow.right") {}
            .pTooltip("Trailing tooltip", placement: .trailing)
    }
    
    PIconButton("arrow.down") {}
        .pTooltip("Bottom tooltip", placement: .bottom)
}

Available Placements

Arrow Indicator

Tooltips include a directional arrow by default:

// With arrow (default)
PButton("Hover me") {}
    .pTooltip("With arrow", showArrow: true)

// Without arrow
PButton("Hover me") {}
    .pTooltip("No arrow", showArrow: false)

Common Patterns

Icon Buttons with Tooltips

Provide context for icon-only buttons:

HStack(spacing: 16) {
    PIconButton("square.and.pencil") {}
        .pTooltip("Edit")
    
    PIconButton("trash") {}
        .variant(.destructive)
        .pTooltip("Delete item")
    
    PIconButton("square.and.arrow.up") {}
        .pTooltip("Share")
    
    PIconButton("ellipsis") {}
        .pTooltip("More options")
}

Form Field Help

Add contextual help to form inputs:

VStack(alignment: .leading, spacing: 8) {
    HStack {
        Text("API Key")
            .font(.subheadline)
            .fontWeight(.medium)
        
        Image(systemName: "questionmark.circle")
            .foregroundColor(.secondary)
            .pTooltip("Your API key can be found in Settings → Developer → API Keys")
    }
    
    PTextField("Enter API key", text: $apiKey)
        .secure()
}

Disabled Button Explanation

Explain why a button is disabled:

PButton("Submit") {
    submit()
}
.disabled(!isFormValid)
.pTooltip(isFormValid ? nil : "Please fill in all required fields")

Navigation Items

Add tooltips to navigation elements:

HStack(spacing: 24) {
    ForEach(navItems) { item in
        PIconButton(item.icon) {
            selectedTab = item.id
        }
        .variant(selectedTab == item.id ? .primary : .ghost)
        .pTooltip(item.label)
    }
}

Interaction Behavior

The tooltip behavior varies by platform:

Styling

Tooltips use theme tokens for consistent appearance:

• Background: Dark background (foreground color with 0.9 opacity)
• Text: Light text (background color)
• Font: Small size with medium weight
• Corner Radius: Uses sm radius token
• Shadow: Subtle shadow for depth

Animation

Tooltips feature smooth, subtle animations:

• Entry: Fade in with slight scale (0.95 → 1.0)
• Exit: Fade out with slight scale (1.0 → 0.95)
• Duration: Quick 200ms transition
• Delay: 500ms delay before showing (prevents accidental triggers)

API Reference

View Modifier

func pTooltip(
    _ text: String?,
    placement: PTooltipPlacement = .top,
    showArrow: Bool = true
) -> some View

Parameters

PTooltipPlacement

public enum PTooltipPlacement {
    case top
    case bottom
    case leading
    case trailing
}

Best Practices

1. Keep text brief - Tooltips should be short hints, not paragraphs
2. Don't hide essential info - Critical information should be visible, not in tooltips
3. Use consistently - If you use tooltips for some icons, use them for all
4. Consider mobile - Remember that mobile users need to long-press
5. Avoid tooltips on tooltips - Don't nest or chain tooltips

Accessibility

• Tooltips are automatically read by VoiceOver
• Text is announced when the user focuses on the element
• Consider adding accessibility labels as a fallback

PIconButton("star") {}
    .pTooltip("Add to favorites")
    .accessibilityLabel("Add to favorites")