Tooltip

A hand-drawn tooltip that reveals a short hint on hover or focus.

Overview

A Tooltip reveals a short, supplementary hint about the element it wraps. It is not for essential information — content must remain usable without ever seeing the tooltip.

Anatomy

A sketchy bubble (@ghds/sketch-core) positioned near a single trigger element and linked to it via aria-describedby. On the web it appears on hover (after a short delay) or focus and hides on leave, blur, or Escape; positioned with floating-ui.

Variants & States

State	Status	Notes
Hidden	Implemented	Default.
Shown	Implemented	On hover (after delay) or focus (web); on tap (React Native).
Disabled	Not implemented	—

Usage

Keep tooltip text short — a few words.
Attach it to a focusable trigger so keyboard and screen-reader users can reveal it.
Use it for supplementary hints only.

Don't

Don't put essential information or interactive controls in a tooltip.
Don't wrap a non-focusable element — the tooltip would be unreachable by keyboard.

Accessibility

React: clones the trigger to add aria-describedby pointing at the role="tooltip" bubble; shows on focus/hover, hides on blur/leave/Escape.
Web Components: sets aria-describedby on the slotted trigger toward the shadow bubble; same hover/focus/Escape behaviour.
React Native: there is no hover on touch, so the tooltip toggles on tap; the content is also exposed as an accessibilityHint on the trigger so it is announced without revealing the bubble.
See the Accessibility Guide.

Content

A short phrase. Long text is capped to a readable max width; keep it concise.

Props API

React`@ghds/react`

Prop	Type	Default	Description
`content`	`ReactNode`	—	Tooltip content.
`children`	`ReactElement`	—	The single trigger element.
`delay`	`number`	`300`	Hover show delay (ms).

Web Components`@ghds/web-components`

Prop	Type	Default	Description
`content`	`string`	—	Tooltip text.
`delay`	`number`	`300`	Hover show delay (ms).
`(slot)`	`element`	—	The trigger element goes in the default slot.

React Native`@ghds/react-native`

Prop	Type	Default	Description
`content`	`string`	—	Tooltip text (also the trigger accessibility hint).
`children`	`ReactNode`	—	The trigger element.
`testID`	`string`	—	Test handle for queries.

Code examples

// React — @ghds/react (hover or focus the trigger)
import { Button } from '@ghds/react/button';
import { Tooltip } from '@ghds/react/tooltip';

<Tooltip content="Saves your changes">
  <Button>Save</Button>
</Tooltip>;

<!-- Web Components — @ghds/web-components (trigger goes in the default slot) -->
<script type="module">
  import '@ghds/web-components/button';
  import '@ghds/web-components/tooltip';
</script>
<gh-tooltip content="Saves your changes">
  <gh-button>Save</gh-button>
</gh-tooltip>

// React Native — @ghds/react-native (tap to toggle)
import { Button } from '@ghds/react-native/button';
import { Tooltip } from '@ghds/react-native/tooltip';

<Tooltip content="Saves your changes">
  <Button label="Save" onPress={save} />
</Tooltip>;

Live Demo

React @ghds/react

Web Components @ghds/web-components

Save