From 852fe2e34ae2e832a2a8ec2888b676e4a16759b1 Mon Sep 17 00:00:00 2001 From: Asish Kumar Date: Fri, 13 Nov 2026 10:53:06 +0530 Subject: [PATCH] feat: add DebugView to visualize safe area insets Add a development helper that draws the insets of the nearest SafeAreaProvider as labeled, translucent bands over its parent. It is absolutely positioned and never intercepts touches, and supports a custom color and hiding the labels. As discussed in #68, it is not exported from the package entry point since React Native does not tree shake. It is published as the react-native-safe-area-context/DebugView subpath, using root level DebugView.js / DebugView.d.ts shims in the same way as jest/mock. Includes tests and an API docs page. --- DebugView.d.ts | 2 + DebugView.js | 1 + docs/docs/api/debug-view.mdx | 42 +++++++++++++++ package.json | 2 + src/DebugView.tsx | 89 ++++++++++++++++++++++++++++++++ src/__tests__/DebugView-test.tsx | 66 +++++++++++++++++++++++ 6 files changed, 202 insertions(+) create mode 100644 DebugView.d.ts create mode 100644 DebugView.js create mode 100644 docs/docs/api/debug-view.mdx create mode 100644 src/DebugView.tsx create mode 100644 src/__tests__/DebugView-test.tsx diff --git a/DebugView.d.ts b/DebugView.d.ts new file mode 100644 index 00000000..ddec8f78 --- /dev/null +++ b/DebugView.d.ts @@ -0,0 +1,2 @@ +export * from './lib/typescript/src/DebugView'; +export { default } from './lib/typescript/src/DebugView'; diff --git a/DebugView.js b/DebugView.js new file mode 100644 index 00000000..bf152d89 --- /dev/null +++ b/DebugView.js @@ -0,0 +1 @@ +module.exports = require('./lib/commonjs/DebugView'); diff --git a/docs/docs/api/debug-view.mdx b/docs/docs/api/debug-view.mdx new file mode 100644 index 00000000..a131d953 --- /dev/null +++ b/docs/docs/api/debug-view.mdx @@ -0,0 +1,42 @@ +--- +sidebar_position: 11 +title: DebugView +sidebar_label: DebugView +--- + +`DebugView` is a development helper that draws the safe area insets of the nearest [`SafeAreaProvider`](./safe-area-provider.mdx) on top of your UI, so you can check visually how your views interact with the safe area. + +It is absolutely positioned, fills its parent and never intercepts touches. Each inset is drawn as a translucent band labeled with its value. + +Since React Native doesn't tree shake, `DebugView` is not exported from the main entry point. Import it from the `react-native-safe-area-context/DebugView` subpath so it is only bundled when you use it. + +### Example + +```tsx +import DebugView from 'react-native-safe-area-context/DebugView'; + +function App() { + return ( + + + {__DEV__ ? : null} + + ); +} +``` + +### Props + +Accepts all [View](https://reactnative.dev/docs/view) props. + +#### `color` + +Optional, defaults to `rgba(255, 0, 0, 0.3)`. + +Color of the bands drawn over the insets. + +#### `showLabels` + +Optional, defaults to `true`. + +Whether to print the value of each inset (for example `top: 47`) in its band. diff --git a/package.json b/package.json index a130c0b0..47972428 100644 --- a/package.json +++ b/package.json @@ -15,6 +15,8 @@ "ios", "common", "jest", + "DebugView.js", + "DebugView.d.ts", "*.podspec", "Package.swift", "react-native.config.js", diff --git a/src/DebugView.tsx b/src/DebugView.tsx new file mode 100644 index 00000000..8bab5f30 --- /dev/null +++ b/src/DebugView.tsx @@ -0,0 +1,89 @@ +import * as React from 'react'; +import { + StyleSheet, + Text, + View, + type ColorValue, + type ViewProps, +} from 'react-native'; +import { useSafeAreaInsets } from './SafeAreaContext'; +import type { Edge } from './SafeArea.types'; + +export interface DebugViewProps extends ViewProps { + /** + * Color of the overlay drawn over the insets. Defaults to a translucent red. + */ + color?: ColorValue; + /** + * Whether to print the inset values. Defaults to `true`. + */ + showLabels?: boolean; +} + +const EDGES: readonly Edge[] = ['top', 'right', 'bottom', 'left']; + +/** + * Development helper that draws the safe area insets of the nearest + * `SafeAreaProvider` on top of its parent. It is absolutely positioned, + * fills the parent and never intercepts touches. + * + * Not exported from the package entry point so that apps that don't use it + * don't bundle it. Import it from `react-native-safe-area-context/DebugView`. + */ +export function DebugView({ + color = 'rgba(255, 0, 0, 0.3)', + showLabels = true, + style, + ...others +}: DebugViewProps) { + const insets = useSafeAreaInsets(); + + return ( + + {EDGES.map((edge) => { + const inset = insets[edge]; + const horizontal = edge === 'top' || edge === 'bottom'; + return ( + + {showLabels ? ( + + {`${edge}: ${inset}`} + + ) : null} + + ); + })} + + ); +} + +const styles = StyleSheet.create({ + edge: { + position: 'absolute', + alignItems: 'center', + justifyContent: 'center', + overflow: 'hidden', + }, + label: { + fontSize: 10, + color: 'white', + fontWeight: 'bold', + }, +}); + +export default DebugView; diff --git a/src/__tests__/DebugView-test.tsx b/src/__tests__/DebugView-test.tsx new file mode 100644 index 00000000..cac25bdd --- /dev/null +++ b/src/__tests__/DebugView-test.tsx @@ -0,0 +1,66 @@ +import { describe, expect, it } from '@jest/globals'; +import { render, screen } from '@testing-library/react-native'; +import * as React from 'react'; +import { StyleSheet } from 'react-native'; +import { DebugView } from '../DebugView'; +import type { Metrics } from '../SafeArea.types'; +import { SafeAreaProvider } from '../SafeAreaContext'; + +const INITIAL_METRICS: Metrics = { + insets: { top: 1, left: 2, right: 3, bottom: 4 }, + frame: { x: 0, y: 0, height: 100, width: 100 }, +}; + +describe('DebugView', () => { + it('draws every inset with its size and label', () => { + render( + + + , + ); + + const top = StyleSheet.flatten( + screen.getByTestId('safe-area-debug-top').props.style, + ); + const bottom = StyleSheet.flatten( + screen.getByTestId('safe-area-debug-bottom').props.style, + ); + const left = StyleSheet.flatten( + screen.getByTestId('safe-area-debug-left').props.style, + ); + const right = StyleSheet.flatten( + screen.getByTestId('safe-area-debug-right').props.style, + ); + + expect(top).toMatchObject({ top: 0, left: 0, right: 0, height: 1 }); + expect(bottom).toMatchObject({ bottom: 0, left: 0, right: 0, height: 4 }); + expect(left).toMatchObject({ left: 0, top: 0, bottom: 0, width: 2 }); + expect(right).toMatchObject({ right: 0, top: 0, bottom: 0, width: 3 }); + expect(screen.getByText('top: 1')).toBeTruthy(); + expect(screen.getByText('right: 3')).toBeTruthy(); + expect(screen.getByText('bottom: 4')).toBeTruthy(); + expect(screen.getByText('left: 2')).toBeTruthy(); + }); + + it('does not intercept touches', () => { + render( + + + , + ); + expect(screen.getByTestId('debug').props.pointerEvents).toBe('none'); + }); + + it('supports a custom color and hiding labels', () => { + render( + + + , + ); + const top = StyleSheet.flatten( + screen.getByTestId('safe-area-debug-top').props.style, + ); + expect(top.backgroundColor).toBe('blue'); + expect(screen.queryByText('top: 1')).toBeNull(); + }); +});