react-native-status-edge

A high-performance, Skia-powered fluid status indicator and dynamic notch animation library for React Native.

Detects your device's screen cutout type (Notch, WaterDrop, Dot/punch-hole, Dynamic Island, or None) and renders a glowing comet animation that perfectly follows the cutout boundary.

Preview

Requirements

• React Native >= 0.71 (New Architecture / TurboModules supported)
• Android API 31+ (Android 12+) for cutout detection
• iOS 13+ / iPhone 11+ for notch/island detection

Installation

npm install react-native-status-edge

Peer Dependencies

This library requires the following peer dependencies to be installed:

npm install @shopify/react-native-skia react-native-reanimated react-native-gesture-handler react-native-safe-area-context

iOS

cd ios && pod install

Usage

Basic — Show a loading animation

import { StatusEdge } from 'react-native-status-edge';

export default function App() {
  return (
    <>
      {/* Your app content */}
      <StatusEdge isLoading={true} color="#00FF00" strokeWidth={3} />
    </>
  );
}

Advanced — Control loading state

import { useState } from 'react';
import { Button, View } from 'react-native';
import { StatusEdge } from 'react-native-status-edge';

export default function App() {
  const [isLoading, setIsLoading] = useState(false);

  const handleFetch = async () => {
    setIsLoading(true);
    await fetchData();
    setIsLoading(false);
  };

  return (
    <View style={{ flex: 1 }}>
      <Button title="Fetch" onPress={handleFetch} />
      <StatusEdge isLoading={isLoading} color="#6366F1" strokeWidth={4} />
    </View>
  );
}

useStatusEdge — Access raw cutout data

import { useStatusEdge } from 'react-native-status-edge';

export default function DebugScreen() {
  const data = useStatusEdge();

  if (!data) return null;

  console.log(data.cutoutType);   // 'Notch' | 'WaterDrop' | 'Dot' | 'Island' | 'None'
  console.log(data.cutoutRects);  // Array of { x, y, width, height } in dp
  console.log(data.safeAreaTop);  // Safe area top inset in dp

  return null;
}

API

<StatusEdge /> Props

useStatusEdge() Hook

Returns StatusEdgeData | null (null while the native module is loading).

interface StatusEdgeData {
  cutoutType: 'Notch' | 'WaterDrop' | 'Dot' | 'Island' | 'None';
  cutoutRects: Array<{ x: number; y: number; width: number; height: number }>;
  cameraCircles: Array<{ cx: number; cy: number; r: number }>;
  safeAreaTop: number;
}

Cutout Types

How it Works

1. Native detection: On Android, DisplayCutout API (API 31+) provides the exact bounding rects and safe inset. On iOS, the device model identifier is matched against a known list to determine the cutout type.
2. Path construction: A Skia path is built to trace the cutout boundary (or screen top edge for None). An EvenOdd clip path prevents the glow from bleeding into the cutout interior.
3. Animation: A withRepeat/withTiming loop drives a start/end offset on the path, creating a comet-tail effect using three layered BlurMask passes for the glow.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library