Cursor Tooltip

Tactile cursor-following tooltip with continuous exponential lerp tracking, boundary viewport collision clamping, multi-variant tokens, and zero Framer Motion dependencies.

CLI Installation

React

$pnpm dlxexhumaaddcursor-tooltip--flavor=react

// 01Workbench

Interactive Specification & Studio

primitives

Preset:

Viewport

Fluid 100%

INTERACTIVE KINETIC TARGET

Exponential Cursor Smoothing

Move your pointer freely across this sandbox. The tooltip trails your cursor using high-performance exponential decay math with viewport collision clamping.

DAMPING: 20DIR: BOTTOM-RIGHTOFFSET: (16px, 16px)VARIANT: FROSTED

Parameters

7 Props

content

springDamping

offsetX

offsetY

variant

direction

collisionPadding

// 02Usage

Quick Start & Consumer Example

Copy-paste ready implementation for React (.tsx). Automatically updates when you modify parameters in the Workbench above.

CursorTooltipDemo.tsx

React (.tsx)

import React from 'react';
import { CursorTooltip } from './CursorTooltip';

export default function CursorTooltipDemo() {
  return (
    <div className="flex min-h-[400px] w-full items-center justify-center p-8 bg-background">
      <CursorTooltip
        content="Explore Showcase"
        springDamping={20}
        direction="bottom-right"
        offsetX={16}
        offsetY={16}
        variant="frosted"
        collisionPadding={12}
        className="rounded-2xl border border-border bg-card/80 p-8 text-center shadow-xl hover:border-primary/50 transition-colors"
      >
        <span className="text-[10px] font-mono font-bold uppercase text-primary mb-2 inline-block">Hover Sandbox</span>
        <h3 className="text-lg font-bold text-foreground">Interactive Target Zone</h3>
        <p className="mt-1 text-xs text-muted-foreground">Move pointer over this card to track trailing tooltip</p>
      </CursorTooltip>
    </div>
  );
}

// 03API Contract

Props & Configuration

Exhaustive parameter contract for Cursor Tooltip. Validated in the live Studio workbench above and statically checked across all 13 ecosystem templates.

Prop	Type	Default	Description
content	string	Explore Showcase	Text or badge label displayed inside the trailing tooltip.
springDamping	number	20	Exponential smoothing factor for trailing cursor physics (higher = snappy, lower = trailing glide).
offsetX	number	16	Horizontal distance from cursor to tooltip origin in pixels.
offsetY	number	16	Vertical distance from cursor to tooltip origin in pixels.
variant	select	frosted	Visual token styling of the floating tooltip badge.
direction	select	bottom-right	Directional orientation and quadrant placement relative to cursor pointer.
collisionPadding	number	12	Safe margin in pixels between tooltip and viewport edges to prevent clipping.

content

string

Text or badge label displayed inside the trailing tooltip.

Default:Explore Showcase

springDamping

number

Exponential smoothing factor for trailing cursor physics (higher = snappy, lower = trailing glide).

Default:20

offsetX

number

Horizontal distance from cursor to tooltip origin in pixels.

Default:16

offsetY

number

Vertical distance from cursor to tooltip origin in pixels.

Default:16

variant

select

Visual token styling of the floating tooltip badge.

Default:frosted

direction

select

Directional orientation and quadrant placement relative to cursor pointer.

Default:bottom-right

collisionPadding

number

Safe margin in pixels between tooltip and viewport edges to prevent clipping.

Default:12

// 04Source Code

Component Source

Component source definition for React (.tsx). Toggle between the clean wrapper and the standalone ejected engine micro-kernel.

CursorTooltip.tsx

import * as React from 'react';
import {
  CursorTooltip as CoreCursorTooltip,
  type CursorTooltipProps as CoreCursorTooltipProps,
  type CursorTooltipVariant,
} from '@exhuma/core';
import { clsx } from 'clsx';

export type { CursorTooltipVariant };

export interface CursorTooltipProps extends CoreCursorTooltipProps {
  className?: string;
}

export const CursorTooltip = React.forwardRef<HTMLDivElement, CursorTooltipProps>(
  (
    {
      content = 'Explore Showcase',
      springDamping = 20,
      direction = 'bottom-right',
      offsetX = 16,
      offsetY = 16,
      variant = 'frosted',
      collisionPadding = 12,
      className,
      children,
      ...props
    },
    ref
  ) => {
    return (
      <CoreCursorTooltip
        content={content}
        springDamping={springDamping}
        direction={direction as any}
        offsetX={offsetX}
        offsetY={offsetY}
        variant={variant as CursorTooltipVariant}
        collisionPadding={collisionPadding}
        className={clsx('relative inline-block cursor-pointer', className)}
        {...props}
      >
        <div ref={ref}>{children}</div>
      </CoreCursorTooltip>
    );
  }
);
CursorTooltip.displayName = 'CursorTooltip';

// 05Architecture

Lifecycle Safety & Performance

Engineered for high-frequency user interactions with zero memory leaks.

Teardown

Deterministic Cleanup

All pointer event listeners, scroll handlers, and resize observers are cleanly destroyed on component unmount, preventing lingering background processes.

Compositor

GPU Compositor Acceleration

Transform and opacity modifications run directly on the GPU compositor thread using will-change: transform without triggering browser layout recalculations.

// 06a11y

Accessibility Considerations

Fully compliant with WCAG guidelines and respects user motion preferences.

Motion

prefers-reduced-motion Support

When a user has prefers-reduced-motion: reduce enabled in their operating system, Exhuma components automatically disable 3D gyroscope tilt and spring animations, rendering static accessible content.

import React from 'react'; import { CursorTooltip } from './CursorTooltip'; export default function CursorTooltipDemo() { return ( <div className="flex min-h-[400px] w-full items-center justify-center p-8 bg-background"> <CursorTooltip content="Explore Showcase" springDamping={20} direction="bottom-right" offsetX={16} offsetY={16} variant="frosted" collisionPadding={12} className="rounded-2xl border border-border bg-card/80 p-8 text-center shadow-xl hover:border-primary/50 transition-colors" > <span className="text-[10px] font-mono font-bold uppercase text-primary mb-2 inline-block">Hover Sandbox</span> <h3 className="text-lg font-bold text-foreground">Interactive Target Zone</h3> <p className="mt-1 text-xs text-muted-foreground">Move pointer over this card to track trailing tooltip</p> </CursorTooltip> </div> ); }

Prop

Type

Default

Description

content

string

Explore Showcase

Text or badge label displayed inside the trailing tooltip.

springDamping

number

Exponential smoothing factor for trailing cursor physics (higher = snappy, lower = trailing glide).

offsetX

number

Horizontal distance from cursor to tooltip origin in pixels.

offsetY

number

Vertical distance from cursor to tooltip origin in pixels.

variant

select

frosted

Visual token styling of the floating tooltip badge.

direction

select

bottom-right

Directional orientation and quadrant placement relative to cursor pointer.

collisionPadding

number

Safe margin in pixels between tooltip and viewport edges to prevent clipping.

import * as React from 'react'; import { CursorTooltip as CoreCursorTooltip, type CursorTooltipProps as CoreCursorTooltipProps, type CursorTooltipVariant, } from '@exhuma/core'; import { clsx } from 'clsx'; export type { CursorTooltipVariant }; export interface CursorTooltipProps extends CoreCursorTooltipProps { className?: string; } export const CursorTooltip = React.forwardRef<HTMLDivElement, CursorTooltipProps>( ( { content = 'Explore Showcase', springDamping = 20, direction = 'bottom-right', offsetX = 16, offsetY = 16, variant = 'frosted', collisionPadding = 12, className, children, ...props }, ref ) => { return ( <CoreCursorTooltip content={content} springDamping={springDamping} direction={direction as any} offsetX={offsetX} offsetY={offsetY} variant={variant as CursorTooltipVariant} collisionPadding={collisionPadding} className={clsx('relative inline-block cursor-pointer', className)} {...props} > <div ref={ref}>{children}</div> </CoreCursorTooltip> ); } ); CursorTooltip.displayName = 'CursorTooltip';