Tooltip

Usage

• Use Tooltip to provide supplementary context about the element or workflow it relates to.
• Never use Tooltip as the primary source of information, and never repeat text the trigger already communicates.
• Use only static, non-interactive content inside a Tooltip.
• Use Popover instead when the content is long-form or contains interactive elements.

Appearance

• Arrow (withArrow, default true) — keep the arrow visible to connect the Tooltip to its trigger, especially when several nearby elements each have their own Tooltip.
• Hide the arrow (withArrow={false}) only in dense layouts where a cleaner look is needed and the trigger association is already evident.
• Underlined trigger (isUnderlined) — apply when the trigger is inline text, to make it visually distinct from surrounding body copy.

Behaviors

• Placement (placement, default "bottom") — accepts "top", "right", "bottom", "left" and their alignment variants (e.g. "top-start"). Choose a placement that avoids covering content the user needs to read.
• Automatic repositioning — the Tooltip repositions when it would overflow the viewport, so placement is a preference and not a guarantee. Pick a sensible default to reduce visual shifting.
• Open state — the Tooltip appears on hover and on focus of the trigger, and dismisses when the user moves away.
• Disabled state (isDisabled) — the Tooltip never opens when the trigger is interacted with.
• Animation (animationTransitionDuration, default 125 ms) — fade plus a directional slide matching the Tooltip's placement.
• Hover delay (floatingPluginOptions.hover.delay, default 250 ms) — prevents accidental activation during normal mouse movement. Adjust as needed.
• Controlled open state (isOpen with onOpenChange) — use together to manage visibility externally. Use defaultIsOpen for an initially open uncontrolled Tooltip.
• Tooltip groups (TooltipGroup / PlumaTooltipGroup) — wrap adjacent Tooltips so they share open/close timing. Once one is open, hovering another trigger in the group opens it immediately without the hover delay.

Content

• Describe what the element is or what it does.
• Limit content to a short phrase or 1–2 short sentences. Use a Popover, or put the content on the page, for anything longer.
• End full sentences with a period or the most relevant punctuation. Omit the period for short action phrases such as "Remove contact".
• Write in sentence case. Never use title case or all caps.
• On icon-only buttons, describe the action the button performs — never the icon name or a generic label.

Implementation Notes

• Pass Tooltip text via the content prop (string). Children define the trigger, not the Tooltip body. Nothing renders when content is empty or the Tooltip is disabled.
• Custom trigger mode (isCustom) — no default trigger wrapper is rendered. Children become a render callback receiving floatingContext, reference, floating, and arrow; wire reference.setReference and reference.getReferenceProps() onto your own element. Required when the trigger is an interactive component such as Button or Link.
• isInline and isUnderlined only exist in default (non-isCustom) mode. isInline (default true) renders the trigger as inline-flex; isInline={false} renders it as flex. isUnderlined has no effect while isDisabled is true.
• The trigger renders as a button by default and as a span when isDisabled is true. Override with the polymorphic as prop.
• unsafe_tooltipClassName and unsafe_tooltipStyle apply to the floating overlay element, not the trigger. Use as a last resort.
• middlewareOptions customizes Floating UI middleware (arrow, offset, flip, shift, hide); additionalMiddleware appends middleware after the defaults. strategy sets the floating element's CSS position (default "absolute").
• floatingPluginOptions configures Floating UI's hover, focus, dismiss, and role behaviors.
• TooltipGroup accepts delay and timeoutMs.
• Ember invocation: <PlumaTooltip @content="Label text">Trigger</PlumaTooltip>. Custom mode yields the Floating UI context: <PlumaTooltip @isCustom={{true}} as |floatingUi|>. The group is <PlumaTooltipGroup @delay={{...}} @timeoutMs={{...}}>.
• Set app-wide defaults for animationTransitionDuration and floatingPluginOptions through PlumaProvider's componentConfig.PlumaTooltip.