svelte-tooltip-gca — Modern tooltips for Svelte 5

Quick start

Install the package and attach the action to any HTML element.

1

Install

npm install svelte-tooltip-gca

Requires svelte ^5.0.0 as a peer dependency.

2

Import

import { tooltip } from 'svelte-tooltip-gca';

Works in SvelteKit, Vite, and any Svelte 5 app.

3

Use

<button use:tooltip={'Hello world'}>
  Hover me
</button>

Pass a string, or an options object for full control.

Minimal example

<script>
  import { tooltip } from 'svelte-tooltip-gca';
</script>

<button use:tooltip={'Saved to drafts'}>
  Save
</button>

<button
  use:tooltip={{
    content: 'Delete permanently',
    placement: 'right',
    delay: 200
  }}
>
  Delete
</button>

Live examples

Hover on desktop or tap on mobile. Tooltips flip when space is tight and stay above other content.

Basic

String shorthand for the most common case.

Placements

Preferred side with automatic flip near viewport edges.

Smart positioning

By default (overflowBehavior: 'shift') the tooltip stays on its preferred side, slides to remain in the viewport, and the arrow re-aims at the target. Resize the window or hover the edge buttons to see it in action.

Delay & animation

Tune show delay and animation duration.

Rich content

Enable HTML for trusted markup (icons, emphasis).

Forced themes

Override auto detection with light or dark.

Custom themes

Pass a partial theme object — only override what you need.

Mobile / touch

On touch devices, tap toggles the tooltip (tap again or outside to dismiss). Long-press is optional and is cancelled if the finger moves — so it never fights with scrolling. On desktop, hover opens and a click dismisses.

Overflow-safe

Rendered via the native popover API in the browser's top-layer — immune to overflow: hidden, stacking contexts, and z-index wars.

Theming

By default tooltips use theme: 'auto'. Detection order: page data-theme / .dark class → CSS color-scheme → prefers-color-scheme.

Custom theme object

import { tooltip } from 'svelte-tooltip-gca';
import type { TooltipTheme } from 'svelte-tooltip-gca';

const myTheme: TooltipTheme = {
  background: '#0ea5e9',
  color: '#fff',
  borderRadius: '12px',
  shadow: '0 12px 30px rgba(14, 165, 233, 0.35)',
  padding: '8px 14px',
  fontSize: '13px'
};

// <button use:tooltip={{ content: 'Sky blue', theme: myTheme }}>…</button>

Theme properties

Property	Type	Description
`background`	string	Panel background (color or gradient)
`color`	string	Text color
`border`	string	Border color
`shadow`	string	CSS box-shadow
`borderRadius`	string	Corner radius
`fontSize`	string	Font size
`fontFamily`	string	Font stack
`fontWeight`	string	Font weight
`padding`	string	Inner padding
`maxWidth`	string	Max width
`arrowSize`	string \| number	Arrow size
`zIndex`	number \| string	Stacking order (default 9999)

API reference

use:tooltip={params} accepts a string or a TooltipOptions object.

Option	Type	Default	Description
`content`	string	—	Tooltip text (required for object form)
`html`	boolean	`false`	Render content as HTML (trusted only)
`placement`	`'top' \| 'bottom' \| 'left' \| 'right'`	`'top'`	Preferred side; auto-flips if needed
`theme`	`'auto' \| 'light' \| 'dark' \| TooltipTheme`	`'auto'`	Built-in mode or custom theme
`offset`	number	`8`	Gap between target and tooltip (px)
`delay`	number	`120`	Show delay (ms)
`hideDelay`	number	`80`	Hide delay (ms)
`arrow`	boolean	`true`	Show pointing arrow
`animation`	boolean	`true`	Enable fade/scale animation
`animationDuration`	number	`160`	Animation duration (ms)
`disabled`	boolean	`false`	Disable the tooltip
`class`	string	`''`	Extra CSS class on the tooltip
`maxWidth`	number \| string	theme default	Override max width
`touchBehavior`	`'tap' \| 'longpress'`	`'tap'`	How touch devices open the tip
`longPressDuration`	number	`400`	Long-press threshold (ms)
`touchHideDelay`	number	`3000`	Auto-hide on touch (`0` = off)
`showOnFocus`	boolean	`true`	Show on keyboard focus
`overflowBehavior`	`'shift' \| 'flip'`	`'shift'`	`'shift'` keeps the preferred side, slides the panel, and re-aims the arrow. `'flip'` tries opposite / perpendicular sides (legacy).
`onShow` / `onHide`	`() => void`	—	Lifecycle callbacks

Exports

import {
  tooltip,          // Svelte action
  lightTheme,       // default light theme object
  darkTheme,        // default dark theme object
  detectDarkMode,   // () => boolean
  resolveTheme      // resolve mode/partial → full theme
} from 'svelte-tooltip-gca';

import type {
  TooltipParams,
  TooltipOptions,
  TooltipTheme,
  TooltipThemeMode,
  TooltipPlacement
} from 'svelte-tooltip-gca';

Behavior notes

Escape dismisses. An open tooltip closes when you press Escape, matching native popover expectations.
Reduced motion. When the OS reports prefers-reduced-motion: reduce, the enter/leave animation is disabled automatically.
Long-press cancels on movement. On touch, a long-press that turns into a scroll or drag is cancelled instead of opening the tooltip.
Live updates. Changing the action's params (content, theme, placement…) while the tooltip is open re-renders and repositions it in place.

Why svelte-tooltip-gca?

✨

Svelte 5 action

use:tooltip on any element — no wrapper components required.

🌓

Auto theme

Detects dark/light from the page or system and switches automatically.

📱

Mobile ready

Tap or long-press on touch devices, with outside-dismiss and auto-hide.

🎹

Keyboard and a11y

Opens on focus, dismisses with Escape, wired up via aria-describedby, and respects prefers-reduced-motion.

🚀

Top-layer rendering

Uses the native popover API so tooltips live in the browser's top-layer, never clipped, never behind a modal.