react-native-focus-guide

A React Native library that provides an elegant way to create interactive focus guides and tooltips. It allows you to highlight specific components and display tooltips with smooth animations, perfect for creating onboarding experiences, feature walkthroughs, and interactive tutorials in your React Native applications.

Features

• 🔍 Highlight any component with a customizable dimmed overlay
• 💬 11 tooltip anchor positions with automatic on-screen clamping & flipping
• 📐 Real tooltip-size measurement — topCenter actually centers, right actually aligns
• 📱 Reactive to orientation, split-screen, and web window resizing
• 🤖 Android status-bar / nav-bar safe by default (translucent Modal — target & overlay share one coordinate space)
• 🎯 Fabric / new-architecture safe (uses measureInWindow on the ref directly)
• ⚡️ Smooth fade-in animation (native-driver) with configurable duration
• 🎨 Customizable overlay color, opacity, hole padding, and hole outline (color / width / radius)
• ☝️ Granular dismiss control (overlay / target hole)

Installation

npm install react-native-focus-guide
# or
yarn add react-native-focus-guide

No native dependencies. Pure JS — works on iOS, Android, and Web (via react-native-web).

Usage

import React, { useRef, useState } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { HighlightToolTip } from 'react-native-focus-guide';

const App = () => {
  const targetRef = useRef(null);
  const [showTooltip, setShowTooltip] = useState(false);

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <TouchableOpacity
        ref={targetRef}
        onPress={() => setShowTooltip(true)}
        style={{ padding: 20, backgroundColor: '#007AFF', borderRadius: 8 }}
      >
        <Text style={{ color: 'white' }}>Click me!</Text>
      </TouchableOpacity>

      <HighlightToolTip
        targetRef={targetRef}
        visible={showTooltip}
        tooltipPosition="bottom"
        onRequestClose={() => setShowTooltip(false)}
      >
        <View
          style={{ padding: 16, backgroundColor: 'white', borderRadius: 8 }}
        >
          <Text>This is a tooltip!</Text>
        </View>
      </HighlightToolTip>
    </View>
  );
};

Tip: prefer driving the tooltip with the visible prop (above) over conditionally mounting {showTooltip && <HighlightToolTip ... />}. Both work, but visible lets the component keep its measured state between opens.

Props

Prop	Type	Default	Description
targetRef	React.RefObject<View>	—	Ref to the component you want to highlight
children	React.ReactNode	—	Content rendered inside the tooltip
onRequestClose	() => void	—	Called when the user dismisses the tooltip
visible	boolean	true	Show / hide the tooltip
tooltipPosition	TooltipPosition	'bottom'	Anchor position relative to the target
offset	{ x?: number; y?: number }	{0, 0}	Extra pixel offset applied to the computed position (clamped to screen bounds)
allowOverlap	boolean	false	Allow the tooltip to overlap with the target (uses a small negative margin)
androidOffsetY	number	0	Manual Y offset on Android. The Modal already renders translucent so coordinates align — use this only for non-standard system-bar setups
overlayColor	string	'#000'	Dim overlay color
overlayOpacity	number	0.6	Dim overlay opacity (0–1)
holePadding	number	0	Extra padding (dp) around the highlighted target
holeBorderColor	string	undefined	Outline color drawn around the highlighted target
holeBorderWidth	number	0	Outline thickness (dp)
holeBorderRadius	number	0	Rounded corners on the outline (dp). Use holePadding >= holeBorderRadius for the cleanest look
dismissOnPress	boolean	true	Close when the user taps the dim overlay
dismissOnTargetPress	boolean	true	Close when the user taps the highlighted target
animationDuration	number	200	Fade-in duration in ms (0 disables the animation)

TooltipPosition

type TooltipPosition =
  | 'top'      | 'bottom'      | 'left'        | 'right'   | 'center'
  | 'topLeft'  | 'topCenter'   | 'topRight'
  | 'bottomLeft' | 'bottomCenter' | 'bottomRight';

When a tooltip would render outside the screen, the component automatically flips to the opposite side and clamps the remaining axis to keep it on-screen — preserving the horizontal alignment you chose.

Advanced usage

Custom styling

Children are rendered verbatim — style them however you like:

<HighlightToolTip
  targetRef={targetRef}
  visible={showTooltip}
  tooltipPosition="bottom"
  overlayColor="#1a1a1a"
  overlayOpacity={0.75}
  holePadding={6}
  onRequestClose={() => setShowTooltip(false)}
>
  <View
    style={{
      padding: 16,
      backgroundColor: 'white',
      borderRadius: 8,
      shadowColor: '#000',
      shadowOffset: { width: 0, height: 2 },
      shadowOpacity: 0.25,
      shadowRadius: 3.84,
      elevation: 5,
    }}
  >
    <Text style={{ fontSize: 16, color: '#333' }}>Custom styled tooltip!</Text>
  </View>
</HighlightToolTip>

Android coordinate correction

The overlay Modal is opened with statusBarTranslucent and navigationBarTranslucent so it covers the entire screen on Android. The component then adds StatusBar.currentHeight to the measured target Y, because measureInWindow on Android returns coordinates in the app's content space (below the status bar), while the translucent Modal renders from y=0 of the physical screen. The default works for the common case (Expo edge-to-edge with SafeAreaView, or apps without edge-to-edge).

If your content renders under the status bar (edge-to-edge, no safe-area padding), the auto-correction will be one status-bar too far down. Cancel it with androidOffsetY:

import { StatusBar } from 'react-native';

<HighlightToolTip
  targetRef={targetRef}
  visible={showTooltip}
  androidOffsetY={-(StatusBar.currentHeight ?? 0)}
  onRequestClose={() => setShowTooltip(false)}
>
  …
</HighlightToolTip>

For other custom system-bar setups, supply a manual pixel offset:

<HighlightToolTip
  targetRef={targetRef}
  visible={showTooltip}
  androidOffsetY={-24}
  tooltipPosition="bottom"
  onRequestClose={() => setShowTooltip(false)}
>
  …
</HighlightToolTip>

Positive values nudge the highlight downward; negative values upward. iOS ignores the prop.

Dismiss behavior

// Only dismiss when tapping the dim overlay, never the target
<HighlightToolTip
  visible={showTooltip}
  dismissOnTargetPress={false}
  onRequestClose={() => setShowTooltip(false)}
  ...
/>

// Programmatic-only dismissal
<HighlightToolTip
  visible={showTooltip}
  dismissOnPress={false}
  dismissOnTargetPress={false}
  onRequestClose={() => setShowTooltip(false)}
  ...
/>

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library