DOCSEARCHbyAlgolia
Submit Docs

react-native-walkthrough-tooltip

repository·master·Indexed 20 days ago

https://github.com/jasongaare/react-native-walkthrough-tooltip

An inline wrapper for React Native components that provides a fullscreen modal to highlight specific UI elements using tooltips. Version 1.6.0 allows developers to create walkthroughs and feature tours by wrapping existing components, using a system that measures element coordinates to render a duplicate of the wrapped element within a modal layer.

Tokens
3.3K
Snippets
8
Records
16
Agent score
69%

What's inside react-native-walkthrough-tooltip

  1. How the Tooltip works

    master
    The Tooltip wraps an element in place within your React Native rendering tree. When displayed, the library uses React Native's measure function to find the element's coordinates. It then renders an absolutely positioned copy of the wrapped element inside a fullscreen modal at those coordinates. This allows users to interact with the highlighted element even though it is technically part of a modal layer above the current screen.

  3. Use the Tooltip component

    master

    The Tooltip component is the primary entry point for creating walkthrough tooltips in React Native. It wraps a target element (the children) and displays a tooltip (content) positioned relative to that element.

    Key Behaviors

    • Targeting: If you provide children, the tooltip will anchor to them. If children is null, the tooltip uses placement: 'center' logic (or an inverted placement) to display relative to the screen.
    • Interaction: By default, the tooltip closes when the user interacts with the background, the tooltip content, or the child element. You can customize this using closeOnBackgroundInteraction, closeOnContentInteraction, and closeOnChildInteraction.
    • Display Modes: You can choose to render the tooltip inside a React Native Modal (default) or as a standard view overlay by setting useReactNativeModal={false}.
    • Child Visibility: If showChildInTooltip is true, the component will attempt to render a duplicate of the children inside the tooltip overlay to create a visual connection.
    import Tooltip from 'react-native-walkthrough-tooltip';
import { View, Text } from 'react-native';

<Tooltip
  isVisible={true}
  content={<Text>This is my tooltip!</Text>}
  onClose={() => console.log('Closed')}
>
  <View>
    <Text>I am the target element</Text>
  </View>
</Tooltip>

  4. Basic usage of Tooltip

    master

    The Tooltip component wraps an element and displays a popover bubble. When isVisible is true, the tooltip renders a fullscreen modal that highlights the wrapped element. You can control visibility via state and specify the content to be displayed in the bubble.

    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>

  5. Manage child element interaction

    master

    The library provides fine-grained control over how users interact with the element being highlighted:

    • allowChildInteraction (bool): If false, the user cannot interact with the child element while the tooltip is visible. Tapping the child will trigger onClose instead. Defaults to true.
    • closeOnChildInteraction (bool): If true, interacting with the child element will trigger the onClose callback (dismissing the tooltip). Defaults to true.
    • showChildInTooltip (bool): If false, the child element will not be displayed alongside the tooltip bubble in the modal. Defaults to true.

  6. Configure Tooltip visibility and content

    master

    Use the following props to control the core behavior of the tooltip:

    • isVisible (bool): Controls whether the tooltip is currently displayed. Defaults to false.
    • content (function/Element): The view/component to be displayed inside the tooltip popover bubble.
    • onClose (function): Callback triggered when the user taps the tooltip background overlay.
    • placement (string): Position of the tooltip. Options: "top", "bottom", "left", "right". Use "center" for childless placement to center the tooltip within displayInsets.

  7. Configure Tooltip display area and insets

    master

    Instead of displayArea, use displayInsets to define the safe area for the tooltip bubble. The tooltip will automatically resize to stay within these bounds.

    • displayInsets (object): An object { top, bottom, left, right } defining pixel insets from each side of the screen. Defaults to { top: 24, bottom: 24, left: 24, right: 24 }.

  8. Distinguish between original and duplicate children using TooltipChildrenContext

    master

    Because the tooltip renders a copy of your child element in a modal, you may need to distinguish between the 'real' child in your layout and the 'duplicate' child in the tooltip. You can use TooltipChildrenContext.Consumer to check the tooltipDuplicate property.

    This is useful for logic like assigning refs only to the original component to avoid issues with the cloned version.

    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>

  9. Customize Tooltip styles

    master

    You can customize the appearance of various parts of the tooltip using these style props:

    • arrowStyle: Styles the triangle pointing to the element.
    • backgroundStyle: Styles the fullscreen overlay behind the tooltip.
    • childrenWrapperStyle: Styles the view wrapping the cloned child.
    • contentStyle: Styles the wrapper surrounding the content element.
    • tooltipStyle: Styles the main tooltip container (arrow + content).

  10. Configure TooltipProps

    master

    The TooltipProps interface defines the configuration for the Tooltip component. It includes controls for visibility, placement, interaction behavior, and content rendering.

    Key Props:

    • isVisible: Boolean determining if the tooltip is shown.
    • content: The React.ReactElement to be displayed inside the tooltip bubble.
    • placement: Where to position the tooltip. Options: 'top', 'bottom', 'left', 'right', or 'center'. (Note: 'center' is only available for childless placement).
    • onClose: Callback function fired when the user taps the tooltip background overlay.
    • allowChildInteraction: Boolean (default true) determining if the user can interact with the child element while the tooltip is visible.
    • closeOnChildInteraction: Boolean (default true) determining if onClose is called when the child element is touched.
    • closeOnContentInteraction: Boolean (default true) determining if onClose is called when the tooltip content is touched.
    • closeOnBackgroundInteraction: Boolean (default true) determining if onClose is called when the background overlay is touched.
    • backgroundColor: String color for the fullscreen background overlay. Overrides backgroundStyle.
    • displayInsets: TooltipDisplayInsets object to inset the tooltip from screen edges.
    • useReactNativeModal: Boolean. If false, the tooltip uses an absolutely positioned view instead of a React Native Modal.
    • useInteractionManager: Boolean. If true, the tooltip waits for InteractionManager.runAfterInteractions before becoming visible.
    • topAdjustment: Number used to adjust the container top value (useful for Android StatusBar fixes).
    • horizontalAdjustment: Number used to tweak the horizontal positioning of the highlighted child element.
    • childContentSpacing: Number representing the distance between the tooltip-rendered child and the arrow.
    <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>

  11. Customize Tooltip styles with TooltipStyleProps

    master

    Use TooltipStyleProps to customize the visual appearance of different parts of the tooltip. These props are passed directly to the Tooltip component.

    Available Style Props:

    • arrowStyle: Styles the triangle pointing to the highlighted element.
    • backgroundStyle: Styles the overlay view behind the tooltip.
    • contentStyle: Styles the wrapper surrounding the content element.
    • tooltipStyle: Styles the main tooltip container (wraps arrow and content).
    • childrenWrapperStyle: Styles the View that wraps the children to clone them.
    • parentWrapperStyle: Styles the View that wraps the original children.

  12. Handle nested elements with TooltipChildrenContext

    master

    The TooltipChildrenContext allows you to handle nested elements within a Tooltip. You can use the TooltipChildrenContext.Consumer to access the tooltipDuplicate boolean, which can be used to disable certain interactions (like scrolling) in nested components to prevent conflicts.

    import Tooltip, { TooltipChildrenContext } from 'react-native-walkthrough-tooltip';

<Tooltip>
    <TooltipChildrenContext.Consumer>
        {({ tooltipDuplicate }) => (
            <ScrollView scrollEnabled={!tooltipDuplicate}>
                {children}
            </ScrollView>
        )}
    </TooltipChildrenContext.Consumer>
</Tooltip>