Skip to main content

Tooltip

A short label for the element it wraps, usually an icon button: "Copy link", "Bold (⌘B)". On the web it shows when the pointer rests on the trigger or keyboard focus reaches it. On touch screens it shows on a long press, for a moment.

import { Tooltip } from 'patine-ui';
Loading…
<HStack gap="sm" style={{ justifyContent: 'center' }}>
  <Tooltip content="Copy link">
    <Button size="icon" variant="outline" accessibilityLabel="Copy link">
      <Icon name="copy" />
    </Button>
  </Tooltip>
  <Tooltip content="Share">
    <Button size="icon" variant="outline" accessibilityLabel="Share">
      <Icon name="share" />
    </Button>
  </Tooltip>
</HStack>

Try the props​

Props
side
align
delayDuration
<Tooltip content="Copy link">
…
</Tooltip>

Example: say why it's disabled​

A blog editor: Publish is off until the post has a title, and its tooltip says so, so nobody wonders why the button won't press. The icon button beside the slug field explains it the same way.

Loading…
<Box border radius="lg" padding="lg" gap="md" style={{ width: '100%', maxWidth: 420 }}>
  <TextField label="Title" placeholder="What’s it about?" value={title} onChangeText={setTitle} />
  <HStack gap="xs" align="center">
    <VStack style={{ flex: 1 }}>
      <Text size="sm" color="textSecondary">Link</Text>
      <Text numberOfLines={1}>blog.example.com/{slug || '…'}</Text>
    </VStack>
    <Tooltip content="Made from the title. You can change it after publishing.">
      <Button size="icon" variant="ghost" accessibilityLabel="About the link">
        <Icon name="info" />
      </Button>
    </Tooltip>
  </HStack>
  <HStack gap="sm" justify="flex-end">
    <Button variant="outline">Save draft</Button>
    <Tooltip content={title.trim() ? 'Publish now' : 'Add a title to publish'}>
      {/* A disabled button gets no hover or focus, so a wrapper takes them for it. */}
      <Pressable accessibilityHint={title.trim() ? undefined : 'Add a title to publish'}>
        <Button disabled={!title.trim()}>Publish</Button>
      </Pressable>
    </Tooltip>
  </HStack>
</Box>

When it shows​

  • Web, pointer: after the pointer rests on the trigger for delayDuration (500ms). It hides when the pointer leaves or the trigger is pressed.
  • Web, keyboard: at once when Tab reaches the trigger, and hides on blur. A mouse click focuses the trigger too, but doesn't show it.
  • Touch screens: a long press shows it for 1.5 seconds, as Android does. The trigger's own onPress and onLongPress still run.
  • Escape hides it on the web, wherever focus is.

Moving straight from one tooltip to the next (within 300ms) opens the next one at once, so a toolbar reads quickly.

Delay​

TooltipProvider is optional. Put one around a screen or the app to change the delay for every tooltip inside it; delayDuration on a Tooltip overrides it for that one.

Loading…
<TooltipProvider delayDuration={300} skipDelayDuration={500}>
  <HStack gap="xs" style={{ justifyContent: 'center' }}>
    {TOOLS.map((tool) => (
      <Tooltip key={tool.label} content={`${tool.label} (${tool.key})`}>
        <Button size="icon" variant="ghost" accessibilityLabel={tool.label}>
          <Icon name={tool.icon} />
        </Button>
      </Tooltip>
    ))}
  </HStack>
</TooltipProvider>

Where it opens​

Above the trigger by default. side picks another ('bottom', 'left', 'right'), align the edge it lines up with, and sideOffset the gap. Like Popover, it flips to the other side when there's no room and stays inside the window.

It measures the trigger itself, so a trigger that floats on its own (a Fab with placement, anything absolutely positioned) gets its tooltip beside it. The trigger should pass its ref on, as the library's buttons do; otherwise the view around it is measured. On the web the tooltip opens in the browser's top layer, so a top bar, a card or a scroll area it's inside can't cover or clip it; in a browser without the Popover API it opens in place.

Designs​

DesignLook
brandA small dark pill.
iosiOS has no tooltips, so a light callout with a hairline border, a soft shadow and an arrow, like an iPad popover.
materialMaterial 3's plain tooltip: a small inverse-surface label with 4dp corners.
webA small dark tooltip with 6px corners.

Pass a node as content to draw your own, or change the box with style.

Accessibility​

A tooltip only adds to its trigger; it never replaces it.

  • The trigger needs its own accessible name: a text label, or accessibilityLabel on an icon button. The tooltip isn't announced in its place.
  • On the web the tooltip has the tooltip role and the trigger points to it with aria-describedby while it's shown, so screen readers read it as a description.
  • It shows on keyboard focus as well as hover, and Escape hides it without moving the pointer.
  • Nothing inside a tooltip can be pressed or focused. For buttons, links or a form, use a Popover.
  • With reduce motion on, it appears without sliding in.

Props​

Tooltip​

PropTypeDefaultDescription
contentReactNoderequiredWhat it says. A string is drawn in the design's text style.
childrenReactElementrequiredOne element with its own accessible name, such as an icon Button. It gets hover, focus and long-press handlers; its own still run.
side'top' | 'bottom' | 'left' | 'right''top'The side of the trigger it opens on; flips when there's no room.
align'start' | 'center' | 'end''center'The trigger edge it lines up with.
sideOffsetnumber4 (6 in brand and iOS)The gap to the trigger.
delayDurationnumberfrom TooltipProvider, 500How long the pointer rests before it shows, in ms.
openboolean—Controlled open state.
defaultOpenbooleanfalseOpen on first render, uncontrolled.
onOpenChange(open: boolean) => void—It showed or hid because of the user. Not called when open changes.
styleStyleProp<ViewStyle>—The tooltip's box.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow: brand, iOS, Material or web, or 'native' for the platform's own.
testIDstring—On the tooltip.

TooltipProvider​

PropTypeDefaultDescription
childrenReactNoderequiredThe tooltips it sets the delay for.
delayDurationnumber500How long the pointer rests on a trigger before its tooltip shows, in ms.
skipDelayDurationnumber300Moving to another trigger within this many ms of a tooltip hiding shows the next one at once.
  • Popover: a panel by its trigger, with content you can press
  • Button: icon buttons, the usual trigger