@data_is_null/tooltip-native-expo

High-performance tooltip for React Native (Expo). Native CADisplayLink/Choreographer tracking at 60-120fps — no JS-thread polling.

Features

• Native tracking — target position tracked via CADisplayLink (iOS) and Choreographer (Android), zero JS bridge overhead for stationary elements
• Spotlight overlay — dim background with a precisely cut-out hole around the target, supports borderRadius for circular/rounded highlights
• Smart positioning — auto-places tooltip where there's room (top, bottom, left, right, auto)
• Animated — spring scale + opacity transitions via Reanimated
• Arrow — directional arrow pointing at the target, follows placement
• Fully customizable — colors, border radius, padding, offset, arrow size, custom content

Installation

npx expo install @data_is_null/tooltip-native-expo

Peer dependencies

npx expo install react-native-reanimated

Quick Start

Wrap your app with TooltipProvider, then use Tooltip around any target element:

import { TooltipProvider, Tooltip } from '@data_is_null/tooltip-native-expo';

function App() {
  return (
    <TooltipProvider>
      <HomeScreen />
    </TooltipProvider>
  );
}

function HomeScreen() {
  const [visible, setVisible] = useState(false);

  return (
    <Tooltip
      visible={visible}
      content={<Text style={{ color: '#fff' }}>Hello!</Text>}
      onDismiss={() => setVisible(false)}
      padding={12}
    >
      <Pressable onPress={() => setVisible(true)}>
        <Text>Tap me</Text>
      </Pressable>
    </Tooltip>
  );
}

Spotlight

Highlight the target element with a dimmed overlay:

<Tooltip
  visible={visible}
  content={<Text style={{ color: '#fff' }}>Check this out</Text>}
  onDismiss={() => setVisible(false)}
  spotlight
  spotlightBorderRadius={16}
  spotlightPadding={8}
  padding={12}
>
  <View style={{ width: 100, height: 100, borderRadius: 16 }}>
    <Text>Target</Text>
  </View>
</Tooltip>

Set spotlightBorderRadius={999} for a circular spotlight around round elements.

API

<TooltipProvider>

Wrap your app (or a subtree) with this provider. Renders the overlay and tooltip bubble above all children.

| Prop | Type | Description | |------|------|-------------| | children | ReactNode | App content |

<Tooltip>

Wraps a target element. Controls visibility and tooltip content.

| Prop | Type | Default | Description | |------|------|---------|-------------| | visible | boolean | — | Show/hide the tooltip | | content | ReactNode | — | Tooltip content | | children | ReactNode | — | Target element | | onDismiss | () => void | — | Called when overlay is tapped | | placement | 'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' | 'auto' | Preferred placement | | offset | number | 8 | Distance from target (px) | | padding | number | 0 | Inner padding of the tooltip bubble | | backgroundColor | string | '#1a1a2e' | Tooltip background color | | borderRadius | number | 8 | Tooltip border radius | | arrowSize | number | 6 | Arrow size (px) | | contentStyle | StyleProp<ViewStyle> | — | Additional style for the tooltip bubble | | spotlight | boolean | false | Enable spotlight overlay | | spotlightPadding | number | 0 | Padding around the spotlight hole | | spotlightBorderRadius | number | 0 | Border radius of the spotlight hole |

How It Works

1. Native tracking: When a tooltip becomes visible, the native module finds the target view by its React tag and starts a display-link callback (CADisplayLink on iOS, Choreographer on Android). Each frame, it checks the view's screen position — if it changed, it emits an event. For stationary targets, zero events are sent after the initial measurement.

2. Spotlight overlay: A single View with a large borderWidth creates a dimmed overlay with a geometrically correct rounded hole — no SVG or masking dependencies required.

3. Positioning: The tooltip bubble position is computed on the JS side using the target rect, available screen space, and preferred placement. If the preferred side doesn't have enough room, it flips to the opposite side.

Platforms

• iOS 15.1+
• Android
• Web (not supported — native module required)

License

MIT