Centrim Design System — a token-first, accessible React component system.
Tooltip, Popover & contextual overlays
Lightweight, trigger-anchored overlays built on the existing V2 overlay foundation — no second implementation, no new tokens.
Overview
Pick the lightest overlay that carries the content.
What is this?
Lightweight overlays anchored to a trigger: Tooltip, Popover, Help popover, Action menu, Context menu and Hover card.
When to use it
- Tooltip — one short, non-interactive explanation
- Popover — contextual information or lightweight interaction
- Help popover — inline “what does this mean?” on a label or filter
- Action / context menu — actions for one specific object
- Hover card — a rich preview of a person or record
How to use it
- Built on the existing V2 overlay foundation — Radix anchoring, semantic z-tokens, shared glass surface.
- Triggers reuse Button and IconButton; contents reuse Select, Checkbox, Badge and Avatar.
- Positioning, offset and collision handling are system-level, never per instance.
What to avoid
- Interactive content inside a Tooltip
- Essential information available only on hover
- New menu, tooltip or overlay implementations
- Arbitrary widths, spacing or z-index values
| Component | Carries | Interactive | Layer |
|---|---|---|---|
| Tooltip | One short phrase | No | z-tooltip |
| Popover | Title, text, controls | Yes | z-popover |
| Menu / Action menu | Actions | Yes | z-dropdown |
| Context menu | Object actions (right-click) | Yes | z-dropdown |
| Hover card | Preview summary | Read-only | z-popover |
| Dialog / Drawer | Focused task or workflow | Yes | modal layers |
Never the only source of information
Essential information must exist in the page itself. Tooltips and hover cards supplement — they never replace a visible label, status or value.
Tooltip
Short explanations for icon-only and abbreviated controls.
Tooltip
A concise explanation shown on hover and on keyboard focus, anchored to its trigger.
import { Tooltip, TooltipProvider } from "@/design-system";
When to use
- Labelling an icon-only control
- Explaining an abbreviated column or metric
- Clarifying an unfamiliar interface element
When not to use
- Content the user must read to complete a task
- Anything interactive — use a Popover
- Long paragraphs, forms or controls
Icon control labels
Wrap the existing IconButton — no custom trigger.
Positioning
Top, bottom, left and right; each repositions automatically near a viewport edge.
Tones
Surface colour of the bubble. `dark` is the default; status tones only where the message itself is a status.
Triggers
Hover (default, also opens on focus), click-to-toggle, or focus only.
Truncated content
Pair with truncated table text so the full value stays reachable.
Popover & help popover
Richer contextual content and inline help.
Popover
A trigger-anchored surface for contextual information or a small amount of interaction.
import { Popover, PopoverContent, PopoverTrigger } from "@/design-system";
When to use
- Explaining a filter or a calculation
- Quick actions attached to a control
- Extra detail that would crowd the page
When not to use
- A single short phrase — use a Tooltip
- A task that deserves full attention — use a Dialog
- A long secondary workflow — use a Drawer
Filter explanation with actions
Read-only detail
HelpPopover
Inline help attached to a label or filter, using the existing IconButton as its trigger.
import { HelpPopover } from "@/design-system";
When to use
- A field whose consequences are not obvious
- Policy or eligibility explanations next to a control
When not to use
- Content that every user needs — put it in helper text
- Anything requiring more than a short paragraph
Service assignment
Info tone with a follow-up action
Menus
Actions for a specific object, from a visible trigger or right-click.
Hover card
Rich previews that are also reachable by keyboard focus.
HoverCard
A read-only preview of a person or record, anchored to an inline reference.
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/design-system";
When to use
- Staff or resident previews on a name
- Service summaries on a reference
When not to use
- Anything interactive — use a Popover
- Critical information that must always be visible
Staff preview
Behaviour & rules
Anchoring, layering and dismissal are system-level, not per-example.
| Concern | Behaviour |
|---|---|
| Anchoring | Every overlay anchors to its trigger with a shared offset; never hard-coded coordinates. |
| Repositioning | Automatic flip and shift with collision padding, so nothing clips the viewport. |
| Width | Tooltips compact; popovers and menus content-appropriate, clamped to the viewport. |
| Layering | Existing semantic z-tokens only — tooltip above popover-level content, dialogs and drawers stay higher. |
| Click outside | Dismisses interactive popovers and menus; guarded surfaces (dialog forms) keep their existing protection. |
| Escape | Closes the active contextual overlay and restores focus to the trigger. |
| Touch | Tooltips respond to tap/focus; interactive content uses popovers and menus, never hover alone. |
Do
- Use a Tooltip for one short phrase, a Popover as soon as content is interactive.
- Trigger inline help with the shared IconButton via HelpPopover.
- Mirror right-click actions with a visible ActionMenu.
- Reuse Button, IconButton, Select, Checkbox and Badge inside popovers.
- Keep destructive menu items on the shared destructive treatment.
Don't
- Put forms, long paragraphs or controls in a Tooltip.
- Hide essential information behind hover.
- Hard-code positions, widths or z-index values.
- Create a second menu, tooltip or overlay implementation.
- Introduce new tooltip, popover, menu or focus colours.