Skip to main content
Design system

Tooltip

Non-actionable UI element that only contains text and does not require the user to take action but serves only to inform the user before taking an action, contextualizing an action, or act as simply supplementary information to an element.

Bundle size: 3.67 kB
Install:
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage:
import { Tooltip } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github

Anatomy

Note: Image is not to scale

  1. Content Container
  2. Arrow

Options

Positioning

The tooltip can be positioned top, left, right, and bottom with each having ability to position at the start, or end of the content container.

Density

There are two options for the property density: compact and default.

Offset

The option offset can use any spacing token to offset its position from the origin point of the tooltip. The default offset is the spacing token 025.


Behavior

Avoids collisions

When appropriate, helper text should be placed closest to the Legend.


Guidance

Do not hide content

A tooltip is not meant to hide necessary contextual information. It should only be used as a supplementary element. The nautre of a tooltip is non-persistent and should not require users to discover content within a tooltip.

Avoid nesting actionable elements

The nautre of the tooltip is non-persistent. When the user is required to take an action on an element nested inside the tooltip it makes the action less accessible for those with limited mobility.

Do not nest Popovers or Tooltips

Tooltips should not have additional tooltips or popover within the same container.


Accessibility

Design considerations

While tooltips are a convenient way of revealing content, please keep in mind the nautre of a tooltip and how it shows/hides on hover. consider alternatives like a more persistent element like a popover.

Keyboard controls

Tooltips will show/hide without delay when the trigger is in focus and tab is selected on the keyboard. If the tooltip is open and either escape, space, or enter is selected on the keyboard, it will close the tooltip.


API Reference

TooltipRoot

PropDescriptionTypeDefaultRequired
open
enum
boolean
----False
defaultOpen
enum
boolean
----False
onOpenChange
(open: boolean) => void
----False
delayDurationThe duration from when the pointer enters the trigger until the tooltip gets opened. This will override the prop with the same name passed to Provider. @defaultValue 700
number
----False
disableHoverableContentWhen `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. @defaultValue false
enum
boolean
----False

TooltipPortal

PropDescriptionTypeDefaultRequired
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False
container
HTMLElement
----False

TooltipProvider

PropDescriptionTypeDefaultRequired
delayDurationThe duration from when the pointer enters the trigger until the tooltip gets opened. @defaultValue 700
number
----False
skipDelayDurationHow much time a user has to enter another trigger without incurring a delay again. @defaultValue 300
number
----False
disableHoverableContentWhen `true`, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger. @defaultValue false
enum
boolean
----False

Tooltip

PropDescriptionTypeDefaultRequired

TooltipContent

PropDescriptionTypeDefaultRequired
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
disabledPrevent the tooltip from showing up
enum
boolean
false False
offsetSide
enum
string | number | WPDSThemeSpaceObject
theme.space[025] False
side
enum
bottom | left | right | top
top False
align
enum
center | end | start
center False
offsetAlign
enum
string | number | WPDSThemeSpaceObject
0 False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False
aria-labelA more descriptive label for accessibility purpose
string
----False
onEscapeKeyDownEvent handler called when the escape key is down. Can be prevented.
(event: KeyboardEvent) => void
----False
onPointerDownOutsideEvent handler called when the a `pointerdown` event happens outside of the `Tooltip`. Can be prevented.
(event: PointerDownOutsideEvent) => void
----False
asChild
enum
boolean
----False
sideOffset
number
----False
alignOffset
number
----False
arrowPadding
number
----False
collisionBoundary
enum
Element | Element[]
----False
collisionPadding
enum
number | Partial<Record<bottom | left | right | top, number>>
----False
sticky
enum
always | partial
----False
hideWhenDetached
enum
boolean
----False
avoidCollisions
enum
boolean
----False
densitySpecify the amount of padding for the inner components.
enum
compact | default
----False

TooltipTrigger

PropDescriptionTypeDefaultRequired
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
asChild
enum
boolean
----False
Edit this page on GitHub.