GkTooltip

A teleported tooltip (default body): v-model visibility, #activator slot with props / is-open, aria-describedby on the activator when open, role="tooltip" on the panel, fixed top / left from useTooltipPosition, Escape and outside mousedown dismiss (unless persistent), optional interactive hover bridge, and text or default slot content.

This is intentionally smaller than Vuetify’s VTooltip: no VOverlay stack, locationStrategy / scrollStrategy beyond anchor + viewport clamping, or transition prop (built-in gk-tooltip transition only).

When to use

Use for short supplemental hints attached to an existing control. Keep content brief and avoid placing essential workflow information only in tooltips.

Live Examples

Hover and focus

Default tooltips open on hover and focus.

vue

<script setup lang="ts">
import { GkButton, GkTooltip } from 'god-kit/vue'
</script>

<template>
  <GkTooltip text="Saved to your profile">
    <template #activator="{ props }">
      <GkButton type="button" v-bind="props">Hover / focus</GkButton>
    </template>
  </GkTooltip>
</template>

Best practice: Always bind activator props so aria-describedby and keyboard triggers stay connected.

Placement

Choose an edge relative to the activator.

vue

<script setup lang="ts">
import { GkButton, GkTooltip } from 'god-kit/vue'
</script>

<template>
  <GkTooltip placement="end" text="Placed on the end side">
    <template #activator="{ props }">
      <GkButton type="button" variant="secondary" v-bind="props">
        End tooltip
      </GkButton>
    </template>
  </GkTooltip>
</template>

Best practice: Keep tooltips close to the control they describe and prefer short text.

Interactive tooltip

Interactive mode lets the pointer enter the tooltip panel.

vue

<script setup lang="ts">
import { GkButton, GkTooltip } from 'god-kit/vue'
</script>

<template>
  <GkTooltip interactive placement="top">
    <template #activator="{ props }">
      <GkButton type="button" variant="secondary" v-bind="props">
        Interactive
      </GkButton>
    </template>

    <span>
      Interactive mode lets the pointer move into the tooltip panel.
    </span>
  </GkTooltip>
</template>

Best practice: Use interactive only when the tooltip has content users must hover into; otherwise keep tooltips passive.

Open on click

Use click-triggered tooltips for touch-friendly hints.

vue

<script setup lang="ts">
import { GkButton, GkTooltip } from 'god-kit/vue'
</script>

<template>
  <GkTooltip
    text="Click toggles this tooltip."
    :open-on-hover="false"
    :open-on-focus="false"
    open-on-click
  >
    <template #activator="{ props }">
      <GkButton type="button" variant="secondary" v-bind="props">
        Click me
      </GkButton>
    </template>
  </GkTooltip>
</template>

Best practice: For essential workflow content, prefer a menu, popover, or dialog over a tooltip.

API

Props

Prop	Type	Default	Description
modelValue	boolean	false	Open state; use v-model
id	string	auto	id on the tooltip panel (for aria-describedby)
text	string	—	Default slot fallback when the default slot is empty
placement	'top' | 'bottom' | 'start' | 'end'	'bottom'	Edge relative to the activator (start / end are LTR-oriented)
offset	number	10	Gap between activator and panel (px)
openOnHover	boolean	true	Open on pointer enter
openOnClick	boolean	false	Toggle on activator click
openOnFocus	boolean	true	Open on focus (keyboard / screen reader)
interactive	boolean	false	Panel receives pointer events; hover can move activator → panel without closing
showDelay	number	0	Delay before open (ms)
hideDelay	number	0	Delay before close from non-interactive leave / focus (ms)
disabled	boolean	false	Disables all open triggers
persistent	boolean	false	Outside mousedown and Escape do not close
to	string | HTMLElement	'body'	Teleport target
zIndex	number | string	--gk-tooltip-z-index	Layer stacking
activatorProps	Record<string, unknown>	—	Merged with internal activator bindings

Additional attributes are applied to the tooltip panel (not the activator).

Slots

Slot	Slot props	Description
activator	props, is-open	Bind v-bind="props" on the focusable control.
default	—	Tooltip content; falls back to text.

Events

Event	Payload	Description
update:modelValue	boolean	Open state
afterEnter	—	Transition finished entering
afterLeave	—	Transition finished leaving

Composable

useTooltipPosition is exported from god-kit/vue for custom fixed tooltips; GkTooltipPlacement is the placement union type.

Tokens

Token	Purpose
--gk-tooltip-z-index	Layer stacking (2200)
--gk-tooltip-max-width	Panel max-width
--gk-tooltip-padding-x / --gk-tooltip-padding-y	Panel padding
--gk-tooltip-shadow	Panel shadow

Try It

Change tooltip placement and trigger options, preview the result, and copy generated Vue code.

placement topbottomstartendtext interactive openOnClick

vue

<script setup lang="ts">
import { GkButton, GkTooltip } from 'god-kit/vue'
</script>

<template>
  <GkTooltip
    text="Short help text."
    placement="bottom"
  >
    <template #activator="{ props }">
      <GkButton type="button" v-bind="props">Help</GkButton>
    </template>
  </GkTooltip>
</template>

Accessibility notes

• Use v-bind=\"props\" from the activator slot so described-by and trigger handlers remain intact.
• Prefer focus-enabled tooltips for keyboard users; hover-only hints are insufficient.
• Keep tooltip text concise and non-interactive unless interactive is explicitly required.

Related components

• GkMenu
• GkOverlay
• GkSnackbar

Out of scope (v1)

VOverlay parity, scrollStrategy / locationStrategy beyond useTooltipPosition, custom transition name prop, and RTL-aware start / end flipping (use direction on a wrapper or app root for RTL).