What is Device Geometry?
Pixel-perfect hardware detection for React Native - Access cutouts, corners, and display metrics
React Native Device Geometry
Pixel-perfect access to your device's physical screen characteristics. Go beyond basic dimensions — get precise SVG paths for cutouts, bezier curves for corners, HDR capabilities, color gamut information, and real-time geometry updates.
Perfect for immersive apps, games, video players, and any UI that needs to adapt to hardware features like Dynamic Island, notches, punch-holes, and rounded corners.
Why Device Geometry?
Standard React Native APIs give you screen width and height. Device Geometry gives you the exact shape of your screen — including cutouts, corners, safe areas, and advanced metrics — all through a simple TypeScript API.
Quick Example
Here's how easy it is to detect and work with hardware features:
import { useDeviceGeometry } from 'react-native-device-geometry';
function App() {
const geometry = useDeviceGeometry();
if (!geometry) return <Loading />;
const hasDynamicIsland = geometry.mainDisplay.cutouts.cutouts.some(
cutout => cutout.shapeType === 'pill'
);
return (
<View style={hasDynamicIsland && { paddingTop: 60 }}>
<YourContent />
</View>
);
}import { DeviceGeometry } from 'react-native-device-geometry';
// Get complete geometry data
const geometry = await DeviceGeometry.getGeometry();
console.log('Screen:', geometry.mainDisplay.metrics);
console.log('Cutouts:', geometry.mainDisplay.cutouts.cutouts);
console.log('Corners:', geometry.mainDisplay.corners);
// Quick checks
const hasCutout = await DeviceGeometry.hasCutout();
const isFoldable = await DeviceGeometry.isFoldable();import { DeviceGeometry, EVENTS } from 'react-native-device-geometry';
// Listen for orientation changes
DeviceGeometry.addListener(
EVENTS.ORIENTATION_CHANGE,
(event) => {
console.log('Device rotated!', event);
updateLayout();
}
);
// Listen for geometry updates
DeviceGeometry.addListener(
EVENTS.GEOMETRY_DID_CHANGE,
async () => {
const newGeo = await DeviceGeometry.getGeometry();
refreshUI(newGeo);
}
);Key Features
Pixel-Perfect Cutouts
Get exact SVG paths for Dynamic Islands, notches, punch-holes, and camera cutouts
Bezier Curves
Extract raw bezier curve data and control points for cutouts and corners
Real-Time Events
Listen to orientation changes, display connections, and geometry updates
Display Metrics
Access HDR capabilities, color gamut (P3, sRGB), refresh rates, and density
Multi-Display Support
Handle external displays, screen mirroring, and display connection events
Foldable Devices
Monitor hinge angles and adapt UI for foldable/dual-screen devices
What You Can Build
Immersive Video Players
Draw edge-to-edge while respecting Dynamic Island and notches
Adaptive Game UIs
Adjust HUD elements around cutouts and corners for any device
Multi-Display Apps
Optimize content for external displays and screen mirroring
Foldable Experiences
Create unique layouts that respond to fold angles
How It Works
Device Geometry bridges native iOS and Android APIs to provide a unified, cross-platform interface for accessing hardware geometry data.
iOS (9.0+)
- Uses
UIWindowSceneandUIBezierPathto extract cutout shapes - Leverages
UIScreenfor metrics and color gamut - Serializes bezier curves into SVG path commands
- Provides corner radius data from
displayCornerRadius
Android (9.0+)
- Leverages
DisplayCutoutAPI for notches and punch-holes - Uses
RoundedCornerAPI for corner geometry (Android 12+) - Accesses
Displayfor metrics, HDR, and wide color gamut - Generates equivalent SVG paths from native shapes
All platform-specific data is normalized into a single TypeScript interface, so you write code once and it works everywhere.
Platform Support
iOS
- iOS 9.0+
- Dynamic Island (iPhone 14 Pro+)
- All notch types (iPhone X+)
- HDR & P3 color gamut
- ProMotion (120Hz)
Android
- Android 9.0+ (API 28+)
- Punch-hole cameras
- Teardrop/waterdrop notches
- Rounded corners (Android 12+)
- Foldable devices
- HDR & wide color gamut
For detailed platform compatibility and API level requirements, see the Platform Support page.
Why Choose Device Geometry?
Compared to Standard APIs
| Feature | React Native Dimensions | Device Geometry |
|---|---|---|
| Screen width/height | Yes | Yes |
| Safe area insets | Yes (via SafeAreaView) | Yes (Recommended to use safe-area-context) |
| Cutout shapes (SVG paths) | No | Yes |
| Corner radius data | No | Yes |
| Bezier curve control points | No | Yes |
| HDR capabilities | No | Yes |
| Color gamut (P3, sRGB) | No | Yes |
| Refresh rate | No | Yes |
| Multi-display support | No | Yes |
| Foldable hinge monitoring | No | Yes |
| Real-time geometry events | No | Yes |
Performance & Developer Experience
High Performance
Zero runtime overhead with native modules and efficient caching
TypeScript-First
Full type safety, IntelliSense, and predictable API
What You Can Build
Explore detailed guides for common use cases:
Dynamic Island Integration
Learn how to detect and work around iPhone's Dynamic Island
Cutout Detection
Comprehensive guide to working with notches and cutouts
Orientation Handling
Handle device rotation and geometry changes
Basic Examples
Get started with simple, practical examples
Quick Start
Get up and running in minutes:
Installation
Install the library and configure for iOS/Android
API Reference
Explore all methods, hooks, and types
Cutout Detection
Learn how to detect and render cutouts
Orientation Handling
Handle device rotation and geometry updates
Ready to build adaptive, hardware-aware UIs? Start with the Quick Start Guide or dive into the API Reference.