Skip to main content

Tooltip

A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it.

Live Demo​

JavaScript
<div className='tooltip-demo-container'>
    <Tooltip.Provider>
      <Tooltip.Root>
        <Tooltip.Trigger className='tooltip-trigger'>
          Hover or Focus Me
        </Tooltip.Trigger>
        <Tooltip.Content className='tooltip-content'>
          Explore
          <Tooltip.Arrow className='tooltip-arrow' />
        </Tooltip.Content>
      </Tooltip.Root>
</Tooltip.Provider>
</div>

The live demo shows a standard tooltip pattern: focus or hover the trigger to reveal a short supporting message above it.

Features​

  • ✅ Controlled and uncontrolled open state (open, defaultOpen, onOpenChange)
  • ✅ Per-tooltip delay control (delay, hideDelay)
  • ✅ Shared timing configuration across multiple tooltips via Tooltip.Provider
  • ✅ Skip-delay behavior between sequential tooltips (skipDelayDuration)
  • ✅ Portal rendering with optional custom container (container)
  • ✅ Floating-based positioning with side and align
  • ✅ Optional arrow part (Tooltip.Arrow)

Import​

import { Tooltip } from '@turkish-technology/spar';

Anatomy​

The Tooltip component is built as a compound component with multiple parts:

Parts
ProviderOptional shared configuration provider
RootState management context
TriggerElement that triggers tooltip
ContentTooltip popup content
ArrowOptional arrow element

Structure​

<Tooltip.Provider>
<Tooltip.Root>
<Tooltip.Trigger>...</Tooltip.Trigger>
<Tooltip.Content>
...
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Root>
</Tooltip.Provider>

Data Flow:

  • Tooltip.Provider: Optional provider for sharing configuration across multiple tooltips
  • Tooltip.Root: Manages tooltip state and provides context to child components
  • Tooltip.Trigger: Element that shows/hides tooltip on hover or focus
  • Tooltip.Content: The actual tooltip popup with smart positioning via Floating UI, automatically portaled to document.body
  • Tooltip.Arrow: Optional arrow element pointing to the trigger

Code Examples​

Basic Tooltip​

Simplest tooltip with default configuration:

export function BasicTooltip() {
return (
<Tooltip.Provider>
<Tooltip.Root>
<Tooltip.Trigger>{'Hover me'}</Tooltip.Trigger>
<Tooltip.Content>Helpful information</Tooltip.Content>
</Tooltip.Root>
</Tooltip.Provider>
);
}

Tooltip with Custom Positioning​

Control tooltip placement and alignment:

<Tooltip.Root>
<Tooltip.Trigger>{'Right aligned tooltip'}</Tooltip.Trigger>
<Tooltip.Content side="right" align="start">
Appears on the right side
</Tooltip.Content>
</Tooltip.Root>

Tooltip with Arrow​

Add an arrow pointing to the trigger element:

<Tooltip.Root>
<Tooltip.Trigger>{'Tooltip with arrow'}</Tooltip.Trigger>
<Tooltip.Content>
Content with arrow
<Tooltip.Arrow />
</Tooltip.Content>
</Tooltip.Root>

Controlled Tooltip State​

Manage tooltip visibility programmatically:

function ControlledTooltip() {
const [open, setOpen] = React.useState(false);

return (
<Tooltip.Root open={open} onOpenChange={setOpen}>
<Tooltip.Trigger>{'Controlled tooltip'}</Tooltip.Trigger>
<Tooltip.Content>Controlled by external state</Tooltip.Content>
</Tooltip.Root>
);
}

Multiple Tooltips with Shared Provider​

Share configuration across multiple tooltips:

<Tooltip.Provider delayDuration={500} skipDelayDuration={200}>
<Tooltip.Root>
<Tooltip.Trigger>{'First tooltip'}</Tooltip.Trigger>
<Tooltip.Content>First tooltip content</Tooltip.Content>
</Tooltip.Root>

<Tooltip.Root>
<Tooltip.Trigger>{'Second tooltip'}</Tooltip.Trigger>
<Tooltip.Content>Second tooltip content</Tooltip.Content>
</Tooltip.Root>
</Tooltip.Provider>

Tooltip with Custom Delays​

Override default delay timing for specific tooltip:

<Tooltip.Root delay={300} hideDelay={100}>
<Tooltip.Trigger>{'Quick tooltip'}</Tooltip.Trigger>
<Tooltip.Content>Shows quickly with custom timing</Tooltip.Content>
</Tooltip.Root>

Disabled Tooltip​

Conditionally disable tooltip:

function DisabledExample() {
const [disabled, setDisabled] = React.useState(false);

return (
<Tooltip.Root disabled={disabled}>
<Tooltip.Trigger>{`Toggle disabled: ${disabled ? 'Yes' : 'No'}`}</Tooltip.Trigger>
<Tooltip.Content>This tooltip can be disabled</Tooltip.Content>
</Tooltip.Root>
);
}

Tooltip with Custom Container​

Render tooltip in custom portal container:

function CustomContainerTooltip() {
const containerRef = React.useRef<HTMLDivElement>(null);

return (
<div>
<div ref={containerRef} />

<Tooltip.Root>
<Tooltip.Trigger>{'Custom container'}</Tooltip.Trigger>
<Tooltip.Content container={containerRef.current || undefined}>
Rendered in custom container
</Tooltip.Content>
</Tooltip.Root>
</div>
);
}

Hoverable Tooltip Content​

Interactive tooltip that remains visible when hovering over the content (WCAG 1.4.13 compliant):

function HoverableTooltip() {
return (
<Tooltip.Provider disableHoverableContent={false}>
<Tooltip.Root hideDelay={300}>
<Tooltip.Trigger>{'Hover to see interactive content'}</Tooltip.Trigger>
<Tooltip.Content>
<div>
<p>You can move your pointer to this content.</p>
<p>It stays visible while hovering!</p>
</div>
</Tooltip.Content>
</Tooltip.Root>
</Tooltip.Provider>
);
}

API Reference​

Tooltip.Provider​

Optional provider for sharing configuration across multiple tooltip instances.

Props

NameTypeDefaultDescription
children?React.ReactNodeundefinedTooltip components to share provider context
delayDuration?number700Global delay duration for all tooltips (ms)
skipDelayDuration?number300Duration to skip delay when moving between (ms)
disableHoverableContent?booleanfalseDisable hoverable content globally

Events

NameParametersDescriptionWhen Triggered
None-Provider manages internal timers-

HTML Attributes

AttributeValuePurpose
None-Provider does not render a DOM element

Tooltip / Tooltip.Root​

Root component that manages tooltip state and provides context to child components. Tooltip and Tooltip.Root are the same component - the difference is only import/notation style.

Props

NameTypeDefaultDescription
id?stringuseId()Base id used to derive trigger/content ids (${id}-trigger, ${id}-content)
children?React.ReactNodeundefinedTooltip trigger/content tree
open?booleanundefinedControlled open state
defaultOpen?booleanfalseInitial state in uncontrolled mode
onOpenChange?(open: boolean) => voidundefinedCalled when open state changes
delay?number700*Show delay for this tooltip (* uses provider delayDuration when present)
hideDelay?number0Hide delay for this tooltip
disabled?booleanfalseDisables open/close state updates

Events

NameParametersDescriptionWhen Triggered
onOpenChange(open: boolean)Tooltip visibility changesUser interaction or control

HTML Attributes

AttributeValuePurpose
None-Root does not render a DOM element

Tooltip.Trigger​

The trigger element that shows/hides the tooltip on hover or focus. Extends all Button component props including polymorphic rendering via the as prop.

Props

NameTypeDefaultDescription
as?React.ElementType"button"Polymorphic trigger element
children?React.ReactNode | ((state: TooltipTriggerRenderProps) => React.ReactNode)undefinedStatic children or render-props function
...propsTooltipTriggerOwnProps & React.ComponentPropsWithoutRef<T>undefinedInherited ButtonOwnProps and native element props

Render Props (TooltipTriggerRenderProps)

PropertyTypeDescription
isOpenbooleanWhether the tooltip is currently visible
disabledbooleanWhether the tooltip is disabled
show() => voidOpens immediately
hide() => voidCloses immediately

Events

NameParametersDescriptionWhen Triggered
onPointerEnter(event: React.PointerEvent)Pointer enters triggerMouse hover or touch start
onPointerLeave(event: React.PointerEvent)Pointer leaves triggerMouse exit or touch end
onFocus(event: React.FocusEvent)Trigger receives focusKeyboard focus
onBlur(event: React.FocusEvent)Trigger loses focusFocus removed
onKeyDown(event: React.KeyboardEvent)Key pressed on triggerKeyboard interaction

HTML Attributes

AttributeValuePurpose
idstringUnique identifier
disabledbooleanDisabled state from Tooltip.Root
aria-describedbystring | undefinedSet to content id when open and enabled
data-state"open" | "closed"Current tooltip state

Tooltip.Content​

The content that displays in the tooltip popup with smart positioning.

Props

NameTypeDefaultDescription
as?React.ElementType"div"Polymorphic content element
side?"top" | "bottom" | "left" | "right""top"Preferred side
align?"start" | "center" | "end""center"Preferred alignment
container?HTMLElement | nulldocument.bodyPortal container (null also falls back to document.body)
onEscapeKeyDown?(event: KeyboardEvent) => voidundefinedCalled on Escape (trigger, content or document) before internal close; preventDefault() keeps it open
...propsReact.ComponentPropsWithoutRef<T>undefinedNative props forwarded to rendered content element

Events

NameParametersDescriptionWhen Triggered
onEscapeKeyDown(event: KeyboardEvent)Escape key pressedUser presses Escape while open; veto with preventDefault
onKeyDown(event: React.KeyboardEvent)Key pressed in contentKeyboard interaction
onMouseEnter(event: React.MouseEvent)Pointer enters contentKeeps content open when hoverable content is enabled
onMouseLeave(event: React.MouseEvent)Pointer leaves contentCloses content when hoverable content is enabled

HTML Attributes

AttributeValuePurpose
idstringUnique identifier
role"tooltip"Tooltip semantic role
data-state"open" | "closed"Visibility state
data-placement"top" | "bottom" | "left" | "right" + optional -start/-center/-endComputed placement from floating logic

Tooltip.Arrow​

Optional decorative arrow pointing to the trigger element. Headless: renders a plain element with no visual opinions — user provides all styling.

Supports polymorphic rendering via the as prop. When rendered as the default svg, sensible SVG defaults (width, height, viewBox, and a triangle polygon) are applied automatically. When rendered as another element (e.g., as="div"), SVG-specific attributes and default children are omitted.

Props

NameTypeDefaultDescription
as?React.ElementType"svg"Polymorphic element type
children?React.ReactNodeundefinedCustom arrow content; default SVG polygon when omitted
...propsReact.ComponentPropsWithoutRef<T>undefinedNative props for rendered element

Events

NameParametersDescriptionWhen Triggered
None-Arrow is purely visual-

HTML Attributes

AttributeValuePurpose
aria-hidden"true"Hidden from assistive technology
data-placement"top" | "bottom" | "left" | "right" + optional -start/-center/-endPlacement metadata
width10 (only when as="svg")Default SVG size
height5 (only when as="svg")Default SVG size
viewBox"0 0 10 5" (only when as="svg")Default SVG viewport

Keyboard Interactions​

Implemented keyboard behavior:

KeyActionContextNotes
TabFocus triggerAny contextShows tooltip immediately on focus
EscapeClose tooltipFocused triggerCloses tooltip and keeps focus on trigger
EscapeClose tooltipFocused contentCloses tooltip and returns focus to trigger