1. Components
  2. Overlays
  3. Tooltip

Tooltip

Tooltip displays a description of an element on hover or focus.

Aria docsReport an issueEdit this page
<Tooltip content={<span>Create new issue <Kbd>C</Kbd></span>}>
  <Button shape="square">
    <SquarePenIcon />
  </Button>
</Tooltip>

Installation

npx dotui-cli@latest add tooltip

Anatomy

import { Tooltip } from "@/components/core/tooltip";
 
<Tooltip content="Edit">
  <Button>
    <EditIcon />
  </Button>
</Tooltip>;
import { TooltipRoot, TooltipContent } from "@/components/core/tooltip";
 
<TooltipRoot>
  <Button>
    <EditIcon />
  </Button>
  <TooltipContent>
    <p>Edit</p>
  </TooltipContent>
</TooltipRoot>;

Usage

Use Tooltip to display a description of an element on hover or focus.

Best practices

  • Use tooltips to describe icons (e.g., icon buttons).
  • Keep the tooltip text minimal.
  • Never include tooltips on non-interactive components (div, span, p) because it will not be accessible for keyboard or screen reader users.
  • Don't place actions inside a tooltip (use Popover instead)

Options

Variant

Use the variant prop to change the appearance of the tooltip.

<Tooltip variant="inverse" content="Create new issue">
  <Button shape="square">
    <SquarePenIcon />
  </Button>
</Tooltip>

Placement

The Tooltip's placement with respect to its trigger element can be adjusted using the placement prop. See the props table for a full list of available placement combinations.

<Tooltip placement="top" content="Create new issue"><Button /></Tooltip>
<Tooltip placement="bottom" content="Create new issue"><Button /></Tooltip>
<Tooltip placement="left" content="Create new issue"><Button /></Tooltip>
<Tooltip placement="right" content="Create new issue"><Button /></Tooltip>

Delay

The delay duration (the time from when the mouse enters a tooltip trigger until the tooltip opens) and the close delay can be customised.

<Tooltip delay={delay} closeDelay={closeDelay} content="Create new issue">
  <Button>
    <PenIcon />
  </Button>
</Tooltip>

Arrow

Use the showArrow prop to add an arrow to the tooltip.

<Tooltip content="Create new issue" arrow>
  <Button>
    <PenIcon />
  </Button>
</Tooltip>

Should flip

This option determines whether or not a tooltip should be able to switch sides when constrained by space.

<Tooltip shouldFlip={shouldFlip} content="Create new issue">
  <Button>
    <PenIcon />
  </Button>
</Tooltip>

Offset

The offset is the distance between the end of the tip and the target.

<Tooltip offset={offset} content="Create new issue">
  <Button>
    <PenIcon />
  </Button>
</Tooltip>

Container padding

To make sure that the tooltip will stay within certain boundaries (e.g., a browser window) it's possible to define a container and a container padding value to respect. The default value for this is 12 px.

<Tooltip containerPadding={containerPadding} content="Create new issue">
  <Button>
    <PenIcon />
  </Button>
</Tooltip>

Composition

For more flexibility, you can drop down to the composition level.

<TooltipRoot>
  <Button>Hover</Button>
  <TooltipContent>
    <p>Create new issue</p>
  </TooltipContent>
</TooltipRoot>

API Reference

Tooltip

PropTypeDefaultDescription
contentReact.ReactNode-The content of the Tooltip
isDisabledboolean-Whether the tooltip should be disabled, independent from the trigger.
delaynumber700The delay time for the tooltip to show up.
closeDelaynumber0The delay time for the tooltip to close.
trigger'focus'-By default, opens for both focus and hover. Can be made to open only for focus.
isOpenboolean-Whether the overlay is open by default (controlled).
defaultOpenboolean-Whether the overlay is open by default (uncontrolled).
triggerRefbooleanRefObject<Element>The ref for the element which the tooltip positions itself with respect to.
When used within a TooltipTrigger this is set automatically. It is only required when used standalone.
isEnteringboolean-Whether the tooltip is currently performing an entry animation.
isExitingboolean-Whether the tooltip is currently performing an exit animation.
placementPlacement'top'The placement of the element with respect to its anchor element.
containerPaddingnumber12The placement padding that should be applied between the element and its surrounding container.
offsetnumber10The additional offset applied along the main axis between the element and its anchor element.
crossOffsetnumber0The additional offset applied along the cross axis between the element and its anchor element.
shouldFlipbooleantrueWhether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
isOpenboolean-Whether the element is rendered.
defaultOpenboolean-Whether the overlay is open by default (uncontrolled).
arrowBoundaryOffsetnumber-The minimum distance the arrow's edge should be from the edge of the overlay element.
childrenbooleanReactNode | (values: TooltipRenderProps & {defaultChildren: ReactNode | undefined}) => ReactNodeThe children of the component. A function may be provided to alter the children based on component state.
EventTypeDescription
onOpenChange(isOpen: boolean) => voidHandler that is called when the overlay's open state changes.

Accessibility

Keyboard interactions

KeyDescription
TabTabbing into an item that has a tooltip associated with it (e.g., a button icon) shows the tooltip.
EscHides the tooltip
DialogThemes
dotUI

Bringing singularity to the web.

Community

Built by mehdibha. The source code is available on GitHub.