# React Native Tooltip

> An accessible React Native tooltip for iOS, Android and the web: shows on hover and keyboard focus on the web, on a long press on touch screens, with a hover delay, flipping and aria-describedby. Brand, iOS, Material 3 and web designs. Pure JavaScript, works in Expo Go.

# 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.

```tsx
import { Tooltip } from 'patine-ui';
```

```tsx live
import { Button, HStack, Tooltip } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <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>
  );
}
```

## 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.

```tsx live
import { useState } from 'react';
import { Pressable } from 'react-native';
import { Box, Button, HStack, Text, TextField, Tooltip, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [title, setTitle] = useState('');
  const slug = title.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
  return (
    <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.

```tsx live
import { Button, HStack, Tooltip, TooltipProvider } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const TOOLS = [
  { label: 'Bold', key: '⌘B', icon: 'bold' },
  { label: 'Italic', key: '⌘I', icon: 'italic' },
  { label: 'Underline', key: '⌘U', icon: 'underline' },
] as const;

export default function Example() {
  return (
    <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`](./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`](./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

| Design | Look |
| --- | --- |
| `brand` | A small dark pill. |
| `ios` | iOS has no tooltips, so a light callout with a hairline border, a soft shadow and an arrow, like an iPad popover. |
| `material` | Material 3's plain tooltip: a small inverse-surface label with 4dp corners. |
| `web` | A 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`](./popover).
- With reduce motion on, it appears without sliding in.

## Props

### Tooltip

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `content` | `ReactNode` | **required** | What it says. A string is drawn in the design's text style. |
| `children` | `ReactElement` | **required** | One 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. |
| `sideOffset` | `number` | `4` (`6` in brand and iOS) | The gap to the trigger. |
| `delayDuration` | `number` | from `TooltipProvider`, `500` | How long the pointer rests before it shows, in ms. |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Open on first render, uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | It showed or hid because of the user. Not called when `open` changes. |
| `style` | `StyleProp<ViewStyle>` | — | The tooltip's box. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
| `testID` | `string` | — | On the tooltip. |

### TooltipProvider

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | **required** | The tooltips it sets the delay for. |
| `delayDuration` | `number` | `500` | How long the pointer rests on a trigger before its tooltip shows, in ms. |
| `skipDelayDuration` | `number` | `300` | Moving to another trigger within this many ms of a tooltip hiding shows the next one at once. |

## Related

- [Popover](./popover): a panel by its trigger, with content you can press
- [Button](./button): icon buttons, the usual trigger
