@phila/phila-ui-tooltip

v0.1.1

Published

6 days ago

Tooltip component for displaying simple or rich content on hover of an element

0High
0Medium
0Low

ui tooltip vue component

Tooltip Component

A tooltip that wraps a trigger element and shows a positioned, teleported bubble on hover or click. Supports a simple single-line ("plain") layout or a richer layout with a title and custom body content.

Installation

pnpm add @phila/phila-ui-tooltip @phila/phila-ui-core
# or
npm install @phila/phila-ui-tooltip @phila/phila-ui-core

Import core styles in your main entry file (e.g., main.js|ts):

import "@phila/phila-ui-core/styles/template-light.css";

Usage

The default slot is the trigger element; the body slot is the bubble's content:

<script setup lang="ts">
import { Tooltip } from "@phila/phila-ui-tooltip";
</script>

<template>
  <Tooltip trigger="hover">
    <button type="button">Hover me</button>
    <template #body>Simple tooltip text</template>
  </Tooltip>
</template>

Rich content, dismissible, click-triggered

<Tooltip type="rich" title="More info" trigger="click" dismissable tail placement="bottom-center">
  <button type="button" aria-label="Info">ⓘ</button>
  <template #body>
    <p>Anything can go here — this is a normal slot, not a text prop.</p>
  </template>
</Tooltip>

Wiring up `aria-describedby`

The default slot is scoped with tooltipId/isOpen, so you can associate the trigger with the bubble for screen readers:

<Tooltip trigger="hover">
  <template #default="{ tooltipId, isOpen }">
    <button type="button" :aria-describedby="isOpen ? tooltipId : undefined">Hover me</button>
  </template>
  <template #body>Extra context</template>
</Tooltip>

Controlling it programmatically

show/hide are exposed on the component instance:

<script setup lang="ts">
import { useTemplateRef } from "vue";

const tooltipRef = useTemplateRef("tooltipRef");
</script>

<template>
  <Tooltip ref="tooltipRef" trigger="click">
    <button type="button">Trigger</button>
    <template #body>Content</template>
  </Tooltip>
  <button type="button" @click="tooltipRef?.show()">Open from elsewhere</button>
</template>

Props

| Prop | Type | Default | Description | | ------------- | --------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type | "plain" \| "rich" | "plain" | plain shows a single line of text; rich allows a title + custom body content. | | color | "default" \| "grey" | "default" | White (default) or grey bubble background. | | tail | boolean | false | Shows a directional tail pointer toward the trigger. | | placement | TooltipPlacement | "auto" | "auto" \| "top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right". Only used when tail is true; "auto" picks a side/alignment based on available viewport space. | | title | string | undefined | Title shown at the top of a rich tooltip. | | dismissable | boolean | false | Renders an X button that hides the tooltip and emits dismiss. Primarily for trigger="click". | | trigger | "hover" \| "click" | "hover" | hover shows on mouseenter/focus (with a short hide delay so you can move the cursor onto the bubble); click toggles on click and closes on outside click or Escape. | | className | string | undefined | Additional CSS classes. |

Slots

| Slot | Scope | Description | | --------- | ---------------------------------------- | --------------------- | | default | { tooltipId: string, isOpen: boolean } | The trigger element. | | body | — | The bubble's content. |

Events

| Event | Payload | Description | | --------- | ------- | -------------------------------------------------------------------------------- | | dismiss | — | Emitted when the dismissable close button is clicked (also hides the tooltip). |

Exposed methods

Access these via a template ref on Tooltip:

| Method | Type | Description | | ------ | ------------ | ---------------------------------- | | show | () => void | Programmatically show the tooltip. | | hide | () => void | Programmatically hide the tooltip. |

Notes

The bubble is teleported to <body> and positioned with fixed coordinates so it escapes any overflow scroll container that would otherwise clip it (e.g. a dropdown or filter panel), and repositions itself on scroll/resize while open.
TooltipBubble is also exported directly if you need the bubble markup without the trigger/positioning behavior Tooltip provides.

Development

Install Dependencies

pnpm install

Run Demo

pnpm dev

Build Library

pnpm build

Type Check

pnpm type-check

Publishing to NPM

Follow the release instructions using changesets.

License

MIT