Home

Awesome

React Native Walkthrough Tooltip npm npm

React Native Walkthrough Tooltip is a fullscreen modal that highlights whichever element it wraps.
When not visible, the wrapped element is displayed normally.

Used by react-native-walkthrough: a lightweight walkthrough library for React Native using react-native-walkthrough-tooltip

Table of Contents

Installation

yarn add react-native-walkthrough-tooltip

Breaking Changes in Version 1.0

For Version 1.0, the library was refactored and simplified.

Changes to handling users pressing the tooltip child element:

Example Usage

To see an expo snack example, click here

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>

Screenshot

<img height ="400" src="example.gif" />

How it works

The tooltip wraps an element in place in your React Native rendering. When it renders, it measures the location of the element, using React Native's measure. When the tooltip is displayed, it renders a copy of the wrapped element positioned absolutely on the screen at the coordinates returned after measuring (see TooltipChildrenContext below if you need to tell the difference between the copy and the original element). This allows you to touch the element in the tooltip modal rendered above your current screen.

Props

Prop nameTypeDefault valueDescription
accessiblebooltrueSet this to false if you do not want the root touchable element to be accessible. See docs on accessible here
allowChildInteractionbooltrueBy default, the user can touch and interact with the child element. When this prop is false, the user cannot interact with the child element while the tooltip is visible.
arrowSizeSize{ width: 16, height: 8 }The dimensions of the arrow on the bubble pointing to the highlighted element
backgroundColorstring'rgba(0,0,0,0.5)'Color of the fullscreen background beneath the tooltip. Overrides the backgroundStyle prop
childContentSpacingnumber4The distance between the tooltip-rendered child and the arrow pointing to it
closeOnChildInteractionbooltrueWhen child interaction is allowed, this prop determines if onClose should be called when the user interacts with the child element. Default is true (usually means the tooltip will dismiss once the user touches the element highlighted)
closeOnContentInteractionbooltruethis prop determines if onClose should be called when the user interacts with the content element. Default is true (usually means the tooltip will dismiss once the user touches the content element)
contentfunction/Element<View />This is the view displayed in the tooltip popover bubble
displayInsetsobject{ top: 24, bottom: 24, left: 24, right: 24 }The number of pixels to inset the tooltip on the screen (think of it like padding). The tooltip bubble should never render outside of these insets, so you may need to adjust your content accordingly
disableShadowboolfalseWhen true, tooltips will not appear elevated. Disabling shadows will remove the warning: RCTView has a shadow set but cannot calculate shadow efficiently on IOS devices.
isVisibleboolfalseWhen true, tooltip is displayed
onClosefunctionnullCallback fired when the user taps the tooltip background overlay
placementstring"top" | "center"Where to position the tooltip - options: top, bottom, left, right, center. Default is top for tooltips rendered with children Default is center for tooltips rendered without children. <br><br>NOTE: center is only available with a childless placement, and the content will be centered within the bounds defined by the displayInsets.
showChildInTooltipbooltrueSet this to false if you do NOT want to display the child alongside the tooltip when the tooltip is visible
supportedOrientationsarray["portrait", "landscape"]This prop allows you to control the supported orientations the tooltip modal can be displayed. It correlates directly with the prop for React Native's Modal component (has no effect if useReactNativeModal is false)
topAdjustmentnumber0Value which provides additional vertical offest for the child element displayed in a tooltip. Commonly set to: Platform.OS === 'android' ? -StatusBar.currentHeight : 0 due to an issue with React Native's measure function on Android
horizontalAdjustmentnumber0Value which provides additional horizontal offest for the child element displayed in a tooltip. This is useful for adjusting the horizontal positioning of a highlighted child element if needed
useInteractionManagerboolfalseSet this to true if you want the tooltip to wait to become visible until the callback for InteractionManager.runAfterInteractions is executed. Can be useful if you need to wait for navigation transitions to complete, etc. See docs on InteractionManager here
useReactNativeModalbooltrueBy default, this library uses a <Modal> component from React Native. If you need to disable this, and simply render an absolutely positioned full-screen view, set useReactNativeModal={false}. This is especially useful if you desire to render a Tooltip while you have a different Modal rendered.

Style Props

The tooltip styles should work out-of-the-box for most use cases, however should you need you can customize the styles of the tooltip using these props.

Prop nameEffect
arrowStyleStyles the triangle that points to the called out element
backgroundStyleStyles the overlay view that sits behind the tooltip, but over the current view
childrenWrapperStyleStyles the view that wraps cloned children
contentStyleStyles the content wrapper that surrounds the content element
tooltipStyleStyles the tooltip that wraps the arrow and content elements

Class definitions for props

TooltipChildrenContext

React Context that can be used to distinguish "real" children rendered inside parent's layout from their copies rendered inside tooltip's modal. The duplicate child rendered in the tooltip modal is wrapped in a Context.Provider which provides object with prop tooltipDuplicate set to true, so informed decisions may be made, if necessary, based on where the child rendered.

import Tooltip, { TooltipChildrenContext } from 'react-native-walkthrough-tooltip';
...
<Tooltip>
  <ComponentA />
  <ComponentB>
    <TooltipChildrenContext.Consumer>
      {({ tooltipDuplicate }) => (
        // will only assign a ref to the original component
        <FlatList {...(!tooltipDuplicate && { ref: this.listRef })} />
      )}
    </TooltipChildrenContext.Consumer>
  </ComponentB>
</Tooltip>