@futurejj/react-native-visibility-sensor

🔍 Component visibility sensor wrapper to sense whether or not a component is in viewport with configurable inset thresholds & percent visibility callback.

Use Cases

• Lazy Loading: Load images/content only when visible to optimize performance in feeds, galleries, charts or webviews.
• Scroll Animations: Trigger animations (e.g., fade-ins, slides) for components entering the viewport.
• Analytics Tracking: Log impressions for ads/banners when visible for a set duration or percentage.
• Dynamic UI & Optimization: Pause/resume videos, cleanup out of screen components or timers based on component visibility in feeds or carousels.

Installation

Using yarn

yarn add @futurejj/react-native-visibility-sensor

using npm:

npm install @futurejj/react-native-visibility-sensor

Usage

import React, { useState } from 'react';
import { ScrollView, Text } from 'react-native';
import { VisibilitySensor } from '@futurejj/react-native-visibility-sensor';

export default function VisibilitySensorExample() {
  const [isVisible, setIsVisible] = useState(false);
  const [percentVisible, setPercentVisible] = useState<number>(0);

  return (
    <ScrollView>
      <VisibilitySensor
        onChange={setIsVisible}
        onPercentChange={setPercentVisible} // optional callback for % change
        threshold={{ top: 100, bottom: 100 }}
        style={[styles.item, { backgroundColor: isVisible ? 'green' : 'red' }]}>
          
        {/* Visibility state */}
        <Text>This View is currently visible? {isVisible ? 'yes' : 'no'}</Text>

        {/* Percent visibility state */}
        <Text>{`Percent visible: ${percentVisible}%`}</Text>
      </VisibilitySensor>
    </ScrollView>
  );
}

Properties

VisibilitySensorProps extends ViewProps from React Native, which includes common properties for all views, such as style, onLayout, etc.

| Property | Type | Required | Description | | ----------------- | ------------------------------------------------------- | -------- | ------------------------------------------------------------ | | onChange | (visible: boolean) => void | Yes | Callback function that fires when visibility changes. | | onPercentChange | (percentVisible: number) => void | No | Callback function that fires when visibility % changes. | | disabled | boolean | No | If true, disables the sensor. | | triggerOnce | boolean | No | If true, the sensor will only trigger once. | | delay | number or undefined | No | The delay in milliseconds before the sensor triggers. | | threshold | VisibilitySensorThreshold | No | Defines the part of the view that must be visible for the sensor to trigger. |

Additionally, all properties from ViewProps are also applicable.

VisibilitySensorThreshold

| Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------ | | top | number | No | The top threshold value for visibility. | | bottom | number | No | The bottom threshold value for visibility. | | left | number | No | The left threshold value for visibility. | | right | number | No | The right threshold value for visibility. |

Notes

1. ⚠️ Facing problem on Android? Refer this discussion: https://github.com/JairajJangle/react-native-visibility-sensor/pull/1#issuecomment-2251569005

Contributing

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

License

MIT

Support the project

❤️ Thanks to

• Module built using create-react-native-library
• Forked & detached from: react-native-component-inview & @se09deluca/react-native-component-inview
• Pokemon image source: PokémonDB
• Readme is edited using Typora