Polarity Integration Component Library

Tooltip Component

A tooltip overlay positioned with Floating UI that supports configurable placement, multiple trigger modes, delays, and an optional arrow.

Installation

npm install @polarityio/pi-tooltip

Peer Dependencies

• lit ^3.0.0

Usage

import '@polarityio/pi-tooltip';

Basic Tooltip (hover + focus)

<button>
  Hover me
  <pi-tooltip>This is a tooltip</pi-tooltip>
</button>

Custom Placement

<button>
  Right tooltip
  <pi-tooltip placement="right">Appears on the right</pi-tooltip>
</button>

Click Trigger

<button>
  Click me
  <pi-tooltip trigger="click">Shown on click</pi-tooltip>
</button>

With Delay and No Arrow

html`
  <button>
    Delayed tooltip
    <pi-tooltip open-delay="500" close-delay="200" ?arrow=${false}> Appears after 500ms </pi-tooltip>
  </button>
`;

Targeting an External Element

<span id="my-target">Hover this text</span>
<pi-tooltip for="my-target" placement="bottom"> Tooltip for the span above </pi-tooltip>

API Reference

Properties

| Property | Type | Default | Description | | ------------ | --------------------- | --------------- | ----------------------------------------------------------------------------------------- | | placement | Placement | 'top' | Where the tooltip appears relative to the target. Reflected to attribute. | | open | boolean | false | Forces the tooltip to be visible. Reflected to attribute. | | disabled | boolean | false | Disables the tooltip. Reflected to attribute. | | delay | number | 0 | Default delay in milliseconds for both opening and closing. | | openDelay | number \| undefined | undefined | Delay before opening in milliseconds. Overrides delay. Set via open-delay attribute. | | closeDelay | number \| undefined | undefined | Delay before closing in milliseconds. Overrides delay. Set via close-delay attribute. | | offset | number | 8 | Distance in pixels between the tooltip and its target. | | arrow | boolean | true | Whether to show an arrow pointing to the target. Reflected to attribute. | | maxWidth | string | '300px' | Maximum width of the tooltip. Set via max-width attribute. | | trigger | string | 'hover focus' | Space-separated trigger types. Reflected to attribute. | | htmlFor | string \| undefined | undefined | ID of an external element to attach the tooltip to. Set via for attribute. |

Placement Values

'top' · 'top-start' · 'top-end' · 'right' · 'right-start' · 'right-end' · 'bottom' · 'bottom-start' · 'bottom-end' · 'left' · 'left-start' · 'left-end'

Trigger Values

| Trigger | Events Used | Description | | ------- | ------------------------------- | ----------------------- | | hover | pointerenter / pointerleave | Show on mouse hover. | | focus | focusin / focusout | Show on keyboard focus. | | click | click | Toggle on click. |

Combine triggers with spaces, e.g. trigger="hover focus".

Events

| Event Name | Detail | Description | | ------------------- | ------------------- | ------------------------------------------------------------------- | | pi-tooltip-change | { open: boolean } | Fired when the tooltip is shown or hidden. Bubbles and is composed. |

Slots

| Slot Name | Description | | ----------- | -------------------------------------- | | (default) | Tooltip content. Accepts text or HTML. |

CSS Custom Properties

| Property | Default | Description | | ------------------------- | --------------------------------------------------- | ------------------------- | | --pi-tooltip-background | var(--pi-color-background-application-4, #2c3240) | Tooltip background color. | | --pi-tooltip-color | var(--pi-color-font-primary, #fafaff) | Tooltip text color. |

Positioning

The tooltip uses @floating-ui/dom for positioning with the following middleware:

• offset — Applies the offset property as spacing from the target.
• flip — Automatically flips placement if the tooltip would overflow the viewport.
• shift — Shifts the tooltip along the axis to stay within the viewport (5px padding).
• arrow — Positions the arrow element when arrow is enabled.

The tooltip is rendered as a fixed-position element appended to document.body.

Accessibility

• Sets aria-describedby on the target element referencing the tooltip.
• Adds tabindex="0" to non-focusable target elements.
• The popup element has role="tooltip".
• Pressing Escape closes the tooltip.

Theming

Customize the appearance using CSS custom properties. This component uses design tokens from @polarityio/pi-shared for consistent theming across the component library.

License

MIT