Skip to main content

Tooltip

Show a short explanation when someone hovers over or focuses an element with a tooltip.

Examples

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
tooltip-demo.tsx
import { Button, Tooltip } from '@uswds-tailwind/react'
export default function TooltipDemo() {
return (
<div className="flex flex-wrap justify-center gap-4 py-12">
<Tooltip content="Top tooltip" position="top"><Button>Top</Button></Tooltip>
<Tooltip content="Right tooltip" position="right"><Button>Right</Button></Tooltip>
<Tooltip content="Bottom tooltip" position="bottom"><Button>Bottom</Button></Tooltip>
<Tooltip content="Left tooltip" position="left"><Button>Left</Button></Tooltip>
</div>
)
}

Component API

Use Root with Trigger and Content, or the Tooltip convenience component for a single trigger.

Root<div>

Owns the tooltip state and text.

PropTypeDefaultDescription
contentstring (required)—Text shown in the tooltip.
positionTooltip positiontopPreferred placement.
defaultOpenboolean—Initially open state.
openboolean—Controlled open state.
onOpenChange({ open: boolean }) => void—Receives requested open-state changes.
ids{ root?: string; trigger?: string; content?: string }—Overrides generated part IDs. Use Root IDs when a label or external control needs a stable input or trigger target.

Escape dismisses an open tooltip. In controlled mode, update open after onOpenChange requests dismissal.

Trigger

Clones its single child element and adds tooltip trigger behavior.

Content<div>

Displays the tooltip text.

AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.
data-placementtop | bottom | left | rightPositions the tooltip.
data-visiblePresent after opening transitionStyles the visible state.

Tooltip

Convenience wrapper around Root, Trigger, and Content.

PropTypeDefaultDescription
contentstring (required)—Tooltip text.
positionTooltip positiontopPreferred placement.

Accessibility

Make the trigger keyboard reachable and name the trigger independently of the tooltip content.