Tooltip - Canvas Design System

When to Use

Use Tooltip when: Providing brief supplementary information for icon buttons, truncated text, or form fields that need extra context. Tooltips should contain concise, non-essential information.

Don't use when: The information is essential for the user to complete a task — use inline text or an Alert instead. Avoid tooltips on mobile-only interfaces where hover isn't available.

Positions

<button <?= ws_tooltip('Helpful info', ['position' => 'top']) ?>>Hover me</button>
<button <?= ws_tooltip('Helpful info', ['position' => 'bottom']) ?>>Hover me</button>
<button <?= ws_tooltip('Helpful info', ['position' => 'left']) ?>>Hover me</button>
<button <?= ws_tooltip('Helpful info', ['position' => 'right']) ?>>Hover me</button>

Variants

<button <?= ws_tooltip('Dark tooltip') ?>>Default</button>
<button <?= ws_tooltip('Light style', ['variant' => 'light']) ?>>Light</button>

Without Arrow

<button <?= ws_tooltip('No arrow', ['arrow' => false]) ?>>Hover me</button>

Parameters

Parameter	Type	Default	Description
`$text`	string	—	Tooltip text content (required)
`position`	string	`top`	`top` \| `bottom` \| `left` \| `right`
`variant`	string	`dark`	`dark` \| `light`
`arrow`	bool	`true`	Show pointer arrow

How It Works

Unlike other components, ws_tooltip() returns HTML attributes rather than a full element. These attributes are placed directly on the target element. The tooltip itself is rendered via CSS ::before / ::after pseudo-elements.

<!-- The helper outputs data attributes like: -->
data-tooltip="Helpful info" data-tooltip-position="top"

CSS Selectors

Selector	Purpose
`[data-tooltip]`	Base tooltip styles (applied via attribute)
`[data-tooltip-position="top"]`	Top position
`[data-tooltip-position="bottom"]`	Bottom position
`[data-tooltip-position="left"]`	Left position
`[data-tooltip-position="right"]`	Right position
`[data-tooltip-variant="light"]`	Light variant styling
`[data-tooltip-arrow="false"]`	Hide arrow

Accessibility

Tooltips follow the WAI-ARIA Tooltip pattern.

ARIA Attributes

Element	Attribute	Value
Trigger element	`aria-describedby`	ID of the tooltip element (when using JS tooltips)
Trigger element	`data-tooltip`	Tooltip text (CSS-only implementation reads this via `content: attr()`)
Tooltip element	`role`	`tooltip`

Keyboard Behavior

Key	Behavior
`Tab` / `Focus`	Tooltip appears when the trigger element receives keyboard focus
`Escape`	Dismisses the tooltip without moving focus
`Tab` (away)	Tooltip disappears when focus leaves the trigger

Implementation Notes

Do: Ensure tooltip triggers are focusable elements (buttons, links, inputs). The CSS-only implementation uses :hover and :focus pseudo-classes, so any focusable trigger works automatically. Tooltips must be dismissable via Escape.

Don't: Don't put essential information in tooltips — screen reader users may miss CSS-only tooltips on non-focusable elements. Never put interactive content (links, buttons) inside a tooltip. Avoid tooltips on touch-only devices where hover isn't available.

Files

File	Purpose
`includes/components/helpers.php`	`ws_tooltip()` helper function
`includes/components/tooltip.php`	Tooltip template (outputs data attributes)
`includes/components/components.css`	Tooltip CSS (pseudo-element styling)