Migrating from ghl-ui Tooltip to HighRise Tooltip

This guide will help you migrate from the ghl-ui Tooltip component to the new HighRise Tooltip component. The Tooltip component has been redesigned with clearer theming controls, an optional header slot, and better defaults aligned to the HighRise design system.

Component Implementation Changes

Import Changes

- import { UITooltip } from '@gohighlevel/ghl-ui'
+ import { HLTooltip } from '@platform-ui/highrise'

Basic Usage Changes

Basic Tooltip

- <UITooltip>
-   <template #trigger>
-     <UIButton>Hover Me</UIButton>
-   </template>
-   This is a tooltip
- </UITooltip>

+ <HLTooltip variant="light">
+   <template #trigger>
+     <HLButton>Hover Me</HLButton>
+   </template>
+   This is a tooltip
+ </HLTooltip>

With Header

- <UITooltip>
-   <template #trigger>
-     <UIButton>With Header</UIButton>
-   </template>
-   <div class="font-bold mb-2">Tooltip Title</div>
-   This is the content
- </UITooltip>

+ <HLTooltip>
+   <template #trigger>
+     <HLButton>With Header</HLButton>
+   </template>
+   <template #header>Tooltip Title</template>
+   This is the content
+ </HLTooltip>

Dark Variant

- <UITooltip>
-   <template #trigger>
-     <UIButton>Dark Theme</UIButton>
-   </template>
-   <div class="bg-gray-800 text-white p-2">Dark tooltip</div>
- </UITooltip>

+ <HLTooltip variant="dark">
+   <template #trigger>
+     <HLButton>Dark Theme</HLButton>
+   </template>
+   Dark tooltip
+ </HLTooltip>

Custom Placement

- <UITooltip placement="top-start">
-   <template #trigger>
-     <UIButton>Custom Placement</UIButton>
-   </template>
-   Tooltip content
- </UITooltip>

+ <HLTooltip placement="top-start">
+   <template #trigger>
+     <HLButton>Custom Placement</HLButton>
+   </template>
+   Tooltip content
+ </HLTooltip>

Props Changes

Required Props

ghl-ui Prop	HighRise Prop	Notes
-	-	No required props; id is optional (useful for testing)

Modified Props

ghl-ui Prop	HighRise Prop	Notes
trigger	trigger	Same options (hover default)
placement	placement	Same placement values
show	show	Same controlled visibility boolean

New Props

Prop	Type	Default	Description
variant	'light' | 'dark'	'light'	Visual style theme (light uses white surface; dark uses gray surface)
headerStyle	Record<string, string>	{}	Inline styles merged into header
contentStyle	Record<string, string>	{}	Inline styles merged into content
tooltipStyle	Record<string, string>	{}	Inline styles merged into the container
disabled	boolean	false	Skip showing the tooltip
to	string | HTMLElement | false	'body'	Target container for teleporting

Emits Changes

ghl-ui Event	HighRise Event	Notes
show	show	Same event with improved type safety (value: boolean)

Slots Changes

ghl-ui Slot	HighRise Slot	Notes
default	default	Main content of the tooltip
trigger	trigger	Element that triggers the tooltip
-	header	New: Dedicated slot for tooltip header content (wrapped with HLText)

Examples

Basic Tooltip with Header

<template>
  <HLTooltip>
    <template #trigger>
      <HLButton>Hover Me</HLButton>
    </template>
    <template #header>Important Info</template>
    This is a tooltip with a header
  </HLTooltip>
</template>

<script setup>
import { HLTooltip, HLButton } from '@platform-ui/highrise'
</script>

Custom Styled Dark Tooltip

<template>
  <HLTooltip
    variant="dark"
    :header-style="{ padding: '12px' }"
    :content-style="{ backgroundColor: '#1a1a1a' }"
    :tooltip-style="{ maxWidth: '320px' }"
  >
    <template #trigger>
      <HLButton>Custom Styled</HLButton>
    </template>
    <template #header>Custom Header</template>
    Styled tooltip content
  </HLTooltip>
</template>

Click Triggered Tooltip

<template>
  <HLTooltip trigger="click">
    <template #trigger>
      <HLButton>Click Me</HLButton>
    </template>
    This tooltip appears on click
  </HLTooltip>
</template>

Manual Control with Events

<template>
  <div>
    <HLButton @click="toggleTooltip">Toggle Tooltip</HLButton>

    <HLTooltip trigger="manual" :show="isVisible" @show="handleShowChange">
      <template #trigger>
        <div class="w-32 h-32 bg-gray-200 flex items-center justify-center">Target Element</div>
      </template>
      Manually controlled tooltip
    </HLTooltip>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { HLTooltip, HLButton } from '@platform-ui/highrise'

const isVisible = ref(false)

const toggleTooltip = () => {
  isVisible.value = !isVisible.value
}

const handleShowChange = value => {
  isVisible.value = value
}
</script>

Breaking Changes

1. Header Implementation

   • New dedicated header slot
   • Replaces custom header div implementation

2. Styling System

   • New variant system (light default, dark available)
   • Separate style props for header/content/container
   • Default spacing, radius, and typography now come from HighRise tokens

3. Content Rendering

   • Default and header slots are wrapped with HLText for consistent typography
   • Expect slight differences in padding and line-height compared to ghl-ui

4. Teleport Target

   • to now defaults to body; override if the tooltip must stay within a scoped container

Best Practices

1. Use appropriate trigger for context (click for actionable, hover for hints)
2. Keep content concise; add header when the body is more than a sentence
3. Favor the default light variant unless the surface is dark
4. Use tooltipStyle instead of deep selectors when possible
5. Keep placement aligned to available space and test at smaller widths

MCPs: prefer passing trigger/placement explicitly and avoid injecting arbitrary HTML; keep variant to light unless the host surface is dark.