Tooltip

Contextual helper text for compact actions and icon-only controls. Tooltips appear on hover and focus while keeping the surrounding layout unchanged.

AccessibleDark ModeAnimatedKeyboard Nav

Install

$npx react-principles add tooltip

Live Demo

Open in Storybookopen_in_new

Code Snippet

src/ui/Tooltip.tsx

import { Tooltip } from "@/ui/Tooltip";

<Tooltip side="top">
  <Tooltip.Trigger>
    <button type="button">Hover me</button>
  </Tooltip.Trigger>
  <Tooltip.Content>Helpful context for this action</Tooltip.Content>
</Tooltip>

Copy-Paste (Single File)

Tooltip.tsx

import { createContext, useContext, useState, type HTMLAttributes, type ReactNode } from "react";
import { cn } from "@/lib/utils";

type TooltipSide = "top" | "bottom" | "left" | "right";

interface TooltipContextValue {
  open: boolean;
  setOpen: (open: boolean) => void;
  side: TooltipSide;
}

const TooltipContext = createContext<TooltipContextValue | null>(null);

function useTooltipContext() {
  const context = useContext(TooltipContext);
  if (!context) throw new Error("Tooltip sub-components must be used inside <Tooltip>");
  return context;
}

export interface TooltipProps {
  defaultOpen?: boolean;
  side?: TooltipSide;
  children: ReactNode;
  className?: string;
}

Props

Prop	Type	Default	Description
`defaultOpen`	`boolean`	`false`	Controls the initial open state before hover or focus interactions occur.
`side`	`"top" \| "bottom" \| "left" \| "right"`	`"top"`	Positions the tooltip relative to its trigger.
`className`	`string`	`—`	Additional classes applied to the tooltip root wrapper.
`Tooltip.Trigger`	`HTMLAttributes<HTMLSpanElement>`	`—`	Wraps the interactive element that opens the tooltip on hover or focus.
`Tooltip.Content`	`HTMLAttributes<HTMLDivElement>`	`—`	Renders the floating tooltip message surface.

react-principles