# Radix UI React Tooltip

Radix UI React Tooltip provides a comprehensive, accessible tooltip component system for React applications. It features sophisticated hover behavior, keyboard navigation, portal rendering, and full ARIA compliance through a compound component pattern.

## Package Information

- **Package Name**: @radix-ui/react-tooltip
- **Package Type**: npm
- **Language**: TypeScript
- **Installation**: `npm install @radix-ui/react-tooltip`

## Core Imports

```typescript
import {
  createTooltipScope,
  TooltipProvider,
  Tooltip,
  TooltipTrigger,
  TooltipPortal,
  TooltipContent,
  TooltipArrow,
} from "@radix-ui/react-tooltip";
```

Alternative short aliases:

```typescript
import {
  Provider,
  Root,
  Trigger,
  Portal,
  Content,
  Arrow,
} from "@radix-ui/react-tooltip";
```

For TypeScript types:

```typescript
import type {
  TooltipProviderProps,
  TooltipProps,
  TooltipTriggerProps,
  TooltipPortalProps,
  TooltipContentProps,
  TooltipArrowProps,
} from "@radix-ui/react-tooltip";
```

## Basic Usage

```typescript
import {
  TooltipProvider,
  Tooltip,
  TooltipTrigger,
  TooltipPortal,
  TooltipContent,
  TooltipArrow,
} from "@radix-ui/react-tooltip";

function MyComponent() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger asChild>
          <button>Hover me</button>
        </TooltipTrigger>
        <TooltipPortal>
          <TooltipContent side="top">
            This is a tooltip!
            <TooltipArrow />
          </TooltipContent>
        </TooltipPortal>
      </Tooltip>
    </TooltipProvider>
  );
}
```

## Architecture

Radix UI React Tooltip uses a compound component pattern with hierarchical structure:

- **Provider Layer**: `TooltipProvider` manages global tooltip behavior and timing
- **Tooltip Instance**: `Tooltip` manages individual tooltip state and controls
- **Interaction Layer**: `TooltipTrigger` handles user interactions (hover, focus, keyboard)
- **Portal Layer**: `TooltipPortal` renders content outside normal DOM flow
- **Content Layer**: `TooltipContent` provides the visible tooltip with positioning and accessibility
- **Visual Enhancement**: `TooltipArrow` adds directional pointer to tooltip

Key design patterns:
- **Context-based state management** for component communication
- **Portal rendering** for z-index and positioning control
- **Sophisticated hover mechanics** with grace areas for smooth user experience  
- **Controlled/uncontrolled state patterns** for flexible integration
- **Accessibility-first design** with ARIA compliance and keyboard navigation

## Capabilities

### Provider Configuration

Global tooltip provider that manages timing, delays, and hover behavior across all tooltips in your application.

```typescript { .api }
interface TooltipProviderProps {
  children: React.ReactNode;
  delayDuration?: number;
  skipDelayDuration?: number;
  disableHoverableContent?: boolean;
}

const TooltipProvider: React.FC<TooltipProviderProps>;
```

[Provider Configuration](./provider.md)

### Tooltip Root Management

Individual tooltip instance that manages open/closed state, timing, and accessibility features.

```typescript { .api }
interface TooltipProps {
  children?: React.ReactNode;
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
  delayDuration?: number;
  disableHoverableContent?: boolean;
}

const Tooltip: React.FC<TooltipProps>;
```

[Tooltip Root Management](./tooltip-root.md)

### Trigger Interaction

Interactive trigger element that responds to hover, focus, and keyboard events to show/hide tooltips.

```typescript { .api }
type TooltipTriggerElement = React.ComponentRef<"button">;
interface TooltipTriggerProps extends React.ComponentPropsWithoutRef<"button"> {
  asChild?: boolean;
}

const TooltipTrigger: React.forwardRef<TooltipTriggerElement, TooltipTriggerProps>;
```

[Trigger Interaction](./trigger.md)

### Portal Rendering and Content Display

Portal component for rendering tooltip content outside the normal DOM hierarchy, plus the main content component with positioning and accessibility features.

```typescript { .api }
interface TooltipPortalProps {
  children?: React.ReactNode;
  container?: HTMLElement;
  forceMount?: true;
}

interface TooltipContentProps {
  forceMount?: true;
  side?: "top" | "right" | "bottom" | "left";
  sideOffset?: number;
  align?: "start" | "center" | "end";
  alignOffset?: number;
  avoidCollisions?: boolean;
  collisionBoundary?: Element | Element[];
  collisionPadding?: number | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
  arrowPadding?: number;
  sticky?: "partial" | "always";
  hideWhenDetached?: boolean;
  'aria-label'?: string;
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
  onPointerDownOutside?: (event: CustomEvent) => void;
}

const TooltipPortal: React.FC<TooltipPortalProps>;
const TooltipContent: React.forwardRef<HTMLDivElement, TooltipContentProps>;
```

[Portal Rendering and Content Display](./portal-content.md)

### Arrow and Visual Enhancement

Optional arrow/pointer component that visually connects the tooltip to its trigger.

```typescript { .api }
interface TooltipArrowProps {
  width?: number;
  height?: number;
  offset?: number;
}

const TooltipArrow: React.forwardRef<SVGSVGElement, TooltipArrowProps>;
```

[Arrow and Visual Enhancement](./arrow.md)

### Utility Functions

Context scoping utilities for advanced tooltip customization and nesting scenarios.

```typescript { .api }
function createTooltipScope(): Scope;
```

[Utility Functions](./utilities.md)

## Types

```typescript { .api }
type TooltipProviderProps = {
  children: React.ReactNode;
  delayDuration?: number;
  skipDelayDuration?: number; 
  disableHoverableContent?: boolean;
};

type TooltipProps = {
  children?: React.ReactNode;
  open?: boolean;
  defaultOpen?: boolean;
  onOpenChange?: (open: boolean) => void;
  delayDuration?: number;
  disableHoverableContent?: boolean;
};

type TooltipTriggerProps = React.ComponentPropsWithoutRef<"button"> & {
  asChild?: boolean;
};

type TooltipPortalProps = {
  children?: React.ReactNode;
  container?: HTMLElement;
  forceMount?: true;
};

type TooltipContentProps = React.ComponentPropsWithoutRef<"div"> & {
  forceMount?: true;
  side?: "top" | "right" | "bottom" | "left";
  sideOffset?: number;
  align?: "start" | "center" | "end";
  alignOffset?: number;
  avoidCollisions?: boolean;
  collisionBoundary?: Element | Element[];
  collisionPadding?: number | Partial<Record<"top" | "right" | "bottom" | "left", number>>;
  arrowPadding?: number;
  sticky?: "partial" | "always";
  hideWhenDetached?: boolean;
  'aria-label'?: string;
  onEscapeKeyDown?: (event: KeyboardEvent) => void;
  onPointerDownOutside?: (event: CustomEvent) => void;
};

type TooltipArrowProps = React.ComponentPropsWithoutRef<"svg"> & {
  width?: number;
  height?: number;
  offset?: number;
};
```