Tooltip
A short explanation that appears on hover or focus.
Installation
pnpm dlx shadcn@latest add https://react-toolbox.io/r/tooltip.json https://react-toolbox.io/r/button.jsonNew here? Set up your project first. Styles, fonts, and required components are included. This example also installs Button for its trigger.
Usage
Wrap a trigger with Tooltip, or use the exported useTooltip hook. Tooltips supplement an accessible label; they should not be the only way to name a control.
Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.
State and callbacks
useTooltip manages visibility from hover, focus, and touch interactions. Pass tooltip content and spread triggerProps onto the trigger, then render its tooltip output. There is no controlled open prop.
Tooltip(Component) and tooltipFactory(options)(Component) create enhanced components; define them outside render. Their tooltip props override factory defaults. Keep essential information visible elsewhere, since tooltips are supplemental.
API reference
Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.
Tooltip
Call Tooltip(Component) outside render. The returned component accepts the original component’s props plus the properties below.
| Property | Type | Default |
|---|---|---|
tooltip | ReactNode | — |
tooltipDelay | number | 0 |
tooltipHideOnClick | boolean | true |
tooltipPosition | TooltipPosition | 'vertical' |
tooltipShowOnClick | boolean | false |
classNames | TooltipThemeClasses for the component's rendered parts. Applied after legacy theme overrides. | — |
themeDeprecated alias | TooltipThemeUse classNames for style slots; use ThemeProvider for design tokens. | — |
Style slots
Pass a map of Tailwind classes to classNames. Available keys:
tooltiptooltipActivetooltipInnertooltipLefttooltipRighttooltipTop
theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.
tooltipFactory
A decorator factory: pass these options, then the component to enhance. Create the enhanced component outside render.
| Property | Type | Default |
|---|---|---|
className | string | — |
delay | number | — |
hideOnClick | boolean | — |
passthrough | boolean | — |
position | TooltipPosition | — |
showOnClick | boolean | — |
classNames | TooltipThemeClasses for the component's rendered parts. Applied after legacy theme overrides. | — |
themeDeprecated alias | TooltipThemeUse classNames for style slots; use ThemeProvider for design tokens. | — |
Style slots
Pass a map of Tailwind classes to classNames. Available keys:
tooltiptooltipActivetooltipInnertooltipLefttooltipRighttooltipTop
theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.
useTooltip
Call this hook inside a React component. Its argument properties are listed below.
| Property | Type | Default |
|---|---|---|
tooltip | ReactNode | — |
tooltipDelay | number | 0 |
tooltipHideOnClick | boolean | true |
tooltipPosition | TooltipPosition | 'vertical' |
tooltipShowOnClick | boolean | false |
classNames | TooltipThemeClasses for the component's rendered parts. Applied after legacy theme overrides. | — |
themeDeprecated alias | TooltipThemeUse classNames for style slots; use ThemeProvider for design tokens. | — |
Also inherits Pick<HTMLAttributes<HTMLElement>, | 'onClick' | 'onMouseEnter' | 'onMouseLeave' | 'onFocus' | 'onBlur' | 'onTouchStart' | 'onTouchEnd' | 'onTouchMove' | 'onTouchCancel' | 'aria-describedby'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.
Style slots
Pass a map of Tailwind classes to classNames. Available keys:
tooltiptooltipActivetooltipInnertooltipLefttooltipRighttooltipTop
theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.
Exported TypeScript types
Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/tooltip.
TooltipTheme
type TooltipTheme = Partial<
Record<'tooltip' | 'tooltipActive' | 'tooltipInner' | 'tooltipLeft' | 'tooltipRight' | 'tooltipTop', string>
>;TooltipClassNames
type TooltipClassNames = TooltipTheme;TooltipPosition
type TooltipPosition = 'bottom' | 'horizontal' | 'left' | 'right' | 'top' | 'vertical';TooltipProps
interface TooltipProps {
tooltip?: ReactNode;
tooltipDelay?: number;
tooltipHideOnClick?: boolean;
tooltipPosition?: TooltipPosition;
tooltipShowOnClick?: boolean;
/** Classes for the component's rendered parts. Applied after legacy theme overrides. */
classNames?: TooltipTheme;
/** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
theme?: TooltipTheme;
}TooltipOptions
interface TooltipOptions {
className?: string;
delay?: number;
hideOnClick?: boolean;
passthrough?: boolean;
position?: TooltipPosition;
showOnClick?: boolean;
/** Classes for the component's rendered parts. Applied after legacy theme overrides. */
classNames?: TooltipTheme;
/** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
theme?: TooltipTheme;
}Material guidelines
- Use short, plain text to clarify an interactive control on hover, focus, or touch long-press. Tooltips do not contain links or other controls.
- Give the trigger its own accessible name. A tooltip supplements that name and should not carry instructions essential to completing the task.