@edux-design/tooltips
v0.2.4
Published
Original Edux tooltip primitives with shared overlay behaviour, motion and colours. Provides `TooltipProvider`, `Tooltip`, `TooltipTrigger`, and `TooltipContent`.
Readme
@edux-design/tooltips
Original Edux tooltip primitives with shared overlay behaviour, motion and colours. Provides TooltipProvider, Tooltip, TooltipTrigger, and TooltipContent.
Token contracts
TooltipContent uses the shared --motion-distance-sm token for its 8px
placement nudge on every side. This keeps tooltip motion aligned with the
popover and overlay primitives without duplicating numeric offsets.
Installation
pnpm add @edux-design/tooltips @edux-design/utils
# or
npm install @edux-design/tooltips @edux-design/utilsPeer deps: react@^19.1.0, react-dom@^19.1.0.
Usage
import {
TooltipProvider,
Tooltip,
TooltipTrigger,
TooltipContent,
} from "@edux-design/tooltips";
export function IconWithTooltip() {
return (
<TooltipProvider>
<Tooltip>
<TooltipTrigger asChild>
<button className="p-2 rounded-md hover:bg-bg-subtle">?</button>
</TooltipTrigger>
<TooltipContent side="bottom" sideOffset={6}>
Helpful hint goes here.
</TooltipContent>
</Tooltip>
</TooltipProvider>
);
}TooltipContent accepts Edux placement props (side, sideOffset) plus className. It automatically renders the arrow and uses a subtle fade/translate animation via Tailwind classes.
Development
pnpm --filter @edux-design/tooltips lint
pnpm --filter @edux-design/tooltips check-types
pnpm --filter @edux-design/tooltips buildStory: src/demos/Tooltip.stories.jsx.
Notes
- Always wrap tooltips in
TooltipProviderso hover/focus delay groups behave as expected. TooltipTriggerforwards native props through the Edux trigger, so you can useasChildto keep DOM output clean.- For accessible labeling, ensure the trigger already has descriptive text or connect it with
aria-label.
Public props, refs and portal ownership
The package exports TooltipProps, TooltipProviderProps,
TooltipTriggerProps and TooltipContentProps. Root and Provider retain controlled/default state and shared delay behaviour. Trigger accepts native button
attributes/events and forwards an HTMLButtonElement ref; use asChild when
composing your own native button. Content forwards an HTMLDivElement ref and
accepts native div attributes/events, placement/collision settings and cancellable
onEscapeKeyDown/onPointerDownOutside handlers.
TooltipContent already renders its portal and arrow. Render it directly inside
Tooltip; an outer Portal is redundant. The content inherits the nearest
Edux theme/brand scope while escaping clipped ancestors. Existing caller style
overrides, including z-index, are preserved.
See DS-26 acceptance for the historical public baseline. Original-engine behaviour is checked in Tooltip.original.test.tsx and the shared installed-consumer browser suite.
Content owns its surface and arrow, so asChild belongs on Trigger.
forceMount keeps both the portal and content mounted when closed; callers
using it manage closed-state visibility for their animation. Closed content is
aria-hidden and inert, so retained animation DOM cannot be announced or
receive focus. When an ancestor overlay closes, explicitly force-mounted content
is retained as a hidden draft (hidden, display: none, and inert); ordinary
content unmounts. Neither draft performs positioning, theme observation, delay or
layer work. Scoped theme and
brand classes, CSS variable overrides and later class/style changes follow the
source scope. Caller-provided content styles take precedence.
Overlay interoperability
Tooltips, Modals, Drawers and Popovers use the same original
@edux-design/overlays foundation. Keep one compatible installed foundation so
Escape dismisses the tooltip first and preserves its parent layer. Package
resolution should be checked from actual component importers, before fixture
aliases or bundler configuration.
The foundation is an ordinary dependency; consumers keep the same four Tooltip
exports. Trigger and content refs remain native button/div refs, and caller
cancellation is honoured. Tooltip Content inherits source theme/brand scope
through its active portal; closed ordinary tooltips allocate no theme observer,
geometry listener or animation loop. forceMount explicitly retains the content
DOM for host-controlled animation visibility.
