@vyshnav18/react-native-fps-counter

High-performance FPS counter for React Native with native UI thread and JS thread tracking. Uses Turbo Modules for maximum performance.

Features

• 🚀 Native UI Thread FPS - Track actual UI performance using native CADisplayLink (iOS) and Choreographer (Android)
• ⚡ JS Thread FPS - Monitor JavaScript thread performance
• 🎯 Turbo Modules - Built with the New Architecture for maximum performance
• 🎨 Draggable Overlay - Beautiful, draggable FPS overlay component
• 🔧 Hooks API - Easy-to-use useFPS hook for custom implementations
• 📊 Warning System - Built-in performance warning detection

Requirements

• React Native 0.72.0 or higher
• React Native New Architecture enabled

Installation

npm install @vyshnav18/react-native-fps-counter
# or
yarn add @vyshnav18/react-native-fps-counter

iOS

cd ios && pod install

Android

No additional setup required.

Usage

Quick Start - FPS Overlay Component

The easiest way to add FPS monitoring to your app:

import { FPSOverlay } from '@vyshnav18/react-native-fps-counter';

function App() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      <FPSOverlay />
    </View>
  );
}

The overlay is draggable and shows both JS and UI thread FPS with color-coded indicators:

• 🟢 Green: 50+ FPS (healthy)
• 🟡 Orange: 30-49 FPS (warning)
• 🔴 Red: < 30 FPS (critical)

FPSOverlay Props

| Prop | Type | Default | Description | | ------------------- | ------- | ------- | ------------------------------------------------ | | initialX | number | 10 | Initial X position of the overlay | | initialY | number | 50 | Initial Y position of the overlay | | showOnlyOnWarning | boolean | false | Only show overlay when FPS drops below threshold |

useFPS Hook

For custom implementations, use the useFPS hook:

import { useFPS } from '@vyshnav18/react-native-fps-counter';

function MyComponent() {
  const { jsFps, uiFps, isWarning, isJsWarning, isUiWarning } = useFPS();

  return (
    <View>
      <Text>JS FPS: {jsFps.toFixed(0)}</Text>
      <Text>UI FPS: {uiFps.toFixed(0)}</Text>
      {isWarning && <Text style={{ color: 'red' }}>Performance Warning!</Text>}
    </View>
  );
}

FPSData Interface

interface FPSData {
  jsFps: number; // JavaScript thread FPS
  uiFps: number; // Native UI thread FPS
  isJsWarning: boolean; // true if JS FPS < 30
  isUiWarning: boolean; // true if UI FPS < 30
  isWarning: boolean; // true if either thread has low FPS
}

Manual Control

Start and stop monitoring manually:

import {
  startMonitoring,
  stopMonitoring,
} from '@vyshnav18/react-native-fps-counter';

// Start monitoring
startMonitoring();

// Stop monitoring
stopMonitoring();

Low-Level JS FPS Tracking

For advanced use cases, subscribe directly to JS FPS updates:

import { subscribeToJsFps } from '@vyshnav18/react-native-fps-counter';

useEffect(() => {
  const unsubscribe = subscribeToJsFps((fps) => {
    console.log('Current JS FPS:', fps);
  });

  return () => unsubscribe();
}, []);

How It Works

JS Thread FPS

Uses requestAnimationFrame to count frames rendered by the JavaScript thread, calculating FPS every second.

UI Thread FPS (Native)

• iOS: Uses CADisplayLink to track the actual screen refresh rate and frame rendering
• Android: Uses Choreographer.FrameCallback to monitor the UI thread frame rate

Both implementations send FPS updates via native events to JavaScript.

Example

Check out the example app for a complete implementation.

# Clone the repository
git clone https://github.com/vyshnav18/react-native-fps-counter.git

# Install dependencies
cd react-native-fps-counter
yarn install

# Run iOS
yarn example ios

# Run Android
yarn example android

Contributing

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

License

MIT

Made with ❤️ by vyshnav18