react-native-walkthrough-tooltip: how the element copy behind the highlight works

A fullscreen modal that highlights the element it wraps

The package description calls it 'An inline wrapper for calling out React Native components via tooltip', and the project README describes it plainly: a fullscreen modal that highlights whichever element it wraps, where the wrapped element is displayed normally when the tooltip is not visible. That is the whole contract. You put a component inside a Tooltip, you control whether it is visible, and the wrapper decides where the bubble goes. The audience is React Native app developers who want a coach mark or onboarding callout over a real, already interactive control, and the library is deliberately narrow about that job. It does not sequence steps, track progress, or hold a tour model. The README names the library that does: react-native-walkthrough, a lightweight walkthrough library for React Native built using this tooltip package. So this is the primitive, and a multi step flow is somebody else's job.

The highlight is a measured copy, not the original component

The interesting mechanism is how the highlight is produced. The tooltip wraps its child in place in the React Native rendering, and when it renders it measures the location of that element using React Native's measure callback. What appears inside the modal is a copy of the wrapped element, positioned absolutely on the screen at the coordinates that measurement returned. The original element is still there underneath, in its normal place in the tree. The copy is what the user sees, and it is what receives the touch, which is why a button inside a tooltip can still be pressed while a modal is displayed above the screen. The README points at a specific context, TooltipChildrenContext, for the case where you need to tell the copy and the original apart in your own code. Because the child is rendered a second time inside the modal, its internal state now exists in two instances, and the documentation does not explain how that state behaves across them, so a child with meaningful internal state deserves a check before you ship it.

Installing the package and rendering a first tooltip

Installation is a single package add, and the version floor is stated up front: the library requires React Native 0.56 or later, and the package manifest repeats that as a peer dependency on react-native at 0.56 or above, alongside a peer dependency on @types/react at 16.8.24 or above.

yarn add react-native-walkthrough-tooltip

The entry point in the manifest is src/tooltip.js, and the runtime dependencies are small: prop-types and react-fast-compare, the latter used to decide whether props actually changed. A first tooltip looks like this, with the visibility flag held in component state, the bubble content passed as a React element, and a placement direction that is now mandatory.

import Tooltip from 'react-native-walkthrough-tooltip';

<Tooltip
  isVisible={this.state.toolTipVisible}
  content={<Text>Check this out!</Text>}
  placement="top"
  onClose={() => this.setState({ toolTipVisible: false })}
>
  <TouchableHighlight style={styles.touchable}>
    <Text>Press me</Text>
  </TouchableHighlight>
</Tooltip>

The placement value here is 'top'. That matters more than it looks, because version 1.0 removed the 'auto' option and a direction must now be specified every time. There is also a useReactNativeModal prop, true by default, that decides whether the bubble content is rendered inside React Native's Modal component or in place.

The bundled Expo app develops straight against src/

The repository ships an Expo application under example/ that imports the library directly from src/ rather than from the published package. The point is deliberate: you develop against the library with hot reload and no build step, so a change to the source shows up in the running app immediately. The example directory has its own package.json, an App.js, a metro.config.js, and a src folder, and the root has a jest.setup.js plus an __tests__ directory for the package's own test run.

cd example
npm install
npm run ios     # or: npm run android

The example covers four screens: placement and displayInsets clamping, a multi step walkthrough, every style prop, and the interaction and dismissal props, including childless tooltips and TooltipChildrenContext. The details live in example/README.md. A separate Expo snack is linked from the README as well, which is the quickest way to see the component on a device without cloning anything. If you want to work on the library itself rather than consume it, that example directory is the intended entry point.

displayInsets replaced displayArea and now clamps the bubble

Version 1.0 was a refactor that simplified the library and broke a good deal of existing usage, so anyone upgrading from 0.6.x needs to know what changed. The displayArea and childlessPlacementPadding props were removed and replaced by a single displayInsets prop, which declares how many pixels in from each side of the screen the tooltip may display in. The old behaviour was leaky: if your content was larger than displayArea, the tooltip could render outside the allowed area. Now the tooltip always resizes to stay inside the region defined by displayInsets. For childless placement, where there is no child element to point at, a 'center' option was added that centers the bubble within the bounds of those insets. A layout that used to overflow now gets clipped or resized instead, which is a visual change in existing apps even where nothing is technically broken.

Child touches now pass through and dismiss the tooltip

The other half of the 1.0 rework concerns what happens when a user touches the highlighted element. The onChildPress and onChildLongPress props are gone, and touches are passed to the child by default, which the README frames as a way to keep the original functionality of the child element. As a consequence the tooltip also dismisses automatically when the user interacts with that child. Two props let you shape that behaviour. closeOnChildInteraction, true by default, decides whether onClose fires when the user interacts with the child, so setting it to false lets the child stay interactive while the bubble remains on screen. allowChildInteraction, also true by default, disables interaction with the child altogether when set to false, and in that case tapping the child calls onClose exactly as if the user had touched the background. The default path is therefore a one tap dismissal, which is convenient but worth confirming against the flow you are building.

Where this tooltip is the wrong tool

Several boundaries are worth naming. First, scope: this is a single tooltip, and a guided tour needs the sequencing layer that react-native-walkthrough provides on top of it. Second, animation is not available. The animated prop was removed in 1.0, and the README directs anyone who needs animated tooltips to the last stable version before the rework, 0.6.1, which means choosing between animation and the current prop API. Third, the highlight depends on one measure round trip and one absolutely positioned copy, and the documentation does not discuss elements inside ScrollViews or virtualized lists, where measured coordinates move. Fourth, the version floor is real: React Native 0.56 or later, and @types/react at 16.8.24 or above. The repository's own development setup still pins react-native 0.55.3 and React 16 in devDependencies alongside Jest 22 and Enzyme 3.3, so the test toolchain trails the declared peer range. Licensing is MIT, which allows use, modification, and redistribution provided the copyright notice and licence text travel with the code.

Editorial conclusion

Adopt react-native-walkthrough-tooltip when you need a single callout bubble around an existing React Native component, you can live without animation, and your app already sits on React Native 0.56 or later. Do not reach for it if you need a multi step onboarding flow, because the sibling react-native-walkthrough library is the layer that builds on top of this one. Check first that your target element sits in a stable position when measured, since the whole highlight depends on one measure round trip and the documentation says nothing about scrolling or virtualized lists.

Frequently asked questions

Official sources

1. Issues
2. jasongaare/react-native-walkthrough-tooltip on GitHub
3. License: MIT
4. README
5. Releases