tessl/npm-react-native-screens
Native navigation primitives for React Native apps with native screen management and transitions.
—
core-functions.mddocs/
Core Functions
Core functionality for enabling and configuring react-native-screens. These functions control the fundamental behavior of native screen implementation and performance optimizations.
Core Imports
import {
enableScreens,
enableFreeze,
screensEnabled,
freezeEnabled
} from "react-native-screens";Capabilities
Enable Screens
Enables or disables the native screen implementation globally. This function should be called early in the app lifecycle, typically in your main index file.
/**
* Enables or disables the native screen implementation
* @param shouldEnableScreens - Whether to enable screens, defaults to true on supported platforms
*/
function enableScreens(shouldEnableScreens?: boolean): void;Usage Example:
import { enableScreens } from "react-native-screens";
// Enable native screens (recommended)
enableScreens(true);
// Disable native screens (fallback to React Native Views)
enableScreens(false);
// Use default behavior (enabled on iOS, Android, Windows)
enableScreens();Platform Support:
- iOS: Uses native UIViewController and UINavigationController
- Android: Uses native Fragment management
- Windows: Native screen support available
- Web: Falls back to React Native View implementation
Enable Freeze
Controls the React Freeze functionality for inactive screens. When enabled, inactive screens are suspended to improve performance and reduce memory usage.
/**
* Enables or disables React freeze functionality for inactive screens
* @param shouldEnableReactFreeze - Whether to enable react-freeze, defaults to true
*/
function enableFreeze(shouldEnableReactFreeze?: boolean): void;Usage Example:
import { enableFreeze } from "react-native-screens";
// Enable React Freeze (recommended for performance)
enableFreeze(true);
// Disable React Freeze
enableFreeze(false);
// Use default behavior (enabled)
enableFreeze();Performance Impact:
- Memory: Inactive screens use significantly less memory when frozen
- CPU: Suspended screens don't consume CPU cycles for re-renders
- Battery: Reduced background processing improves battery life
- Compatibility: Works with React 18+ concurrent features
Check Screens Status
Returns whether native screens are currently enabled in the application.
/**
* Returns whether screens are currently enabled
* @returns true if native screens are active, false if using fallback
*/
function screensEnabled(): boolean;Usage Example:
import { screensEnabled } from "react-native-screens";
if (screensEnabled()) {
console.log("Using native screen implementation");
} else {
console.log("Using React Native View fallback");
}
// Conditional logic based on screen implementation
const useNativeGestures = screensEnabled();Check Freeze Status
Returns whether React Freeze functionality is currently enabled.
/**
* Returns whether freeze functionality is currently enabled
* @returns true if React Freeze is active for inactive screens
*/
function freezeEnabled(): boolean;Usage Example:
import { freezeEnabled } from "react-native-screens";
if (freezeEnabled()) {
console.log("Inactive screens will be frozen for performance");
} else {
console.log("All screens remain active");
}
// Adjust memory usage expectations
const expectedMemoryUsage = freezeEnabled() ? "low" : "high";Configuration Timing
App Initialization
These functions should be called during app initialization, before any screen components are rendered:
// index.js or App.tsx
import { enableScreens, enableFreeze } from "react-native-screens";
import { AppRegistry } from 'react-native';
import App from './App';
// Configure before app starts
enableScreens(true);
enableFreeze(true);
AppRegistry.registerComponent('MyApp', () => App);Conditional Enabling
Enable screens based on platform or feature detection:
import { Platform } from 'react-native';
import { enableScreens } from "react-native-screens";
// Platform-specific enabling
if (Platform.OS === 'ios' || Platform.OS === 'android') {
enableScreens(true);
} else {
enableScreens(false);
}Development vs Production
Different configurations for development and production builds:
import { enableScreens, enableFreeze } from "react-native-screens";
if (__DEV__) {
// Development: Enable screens but disable freeze for debugging
enableScreens(true);
enableFreeze(false);
} else {
// Production: Enable both for optimal performance
enableScreens(true);
enableFreeze(true);
}Compatibility
React Navigation Integration
When using React Navigation, these functions integrate automatically:
// React Navigation v6+ automatically enables screens when installed
// Manual enabling is optional but recommended for explicit control
import { enableScreens } from "react-native-screens";
enableScreens(true);Legacy Support
For apps upgrading from older navigation solutions:
import { enableScreens, screensEnabled } from "react-native-screens";
// Gradual migration approach
enableScreens(true);
// Check if migration was successful
if (screensEnabled()) {
console.log("Successfully migrated to native screens");
} else {
console.log("Fallback to previous implementation");
}Troubleshooting
Common Issues
- Screens not enabling: Ensure the function is called before rendering any screen components
- Performance degradation: Check if freeze is disabled when it should be enabled
- Platform compatibility: Verify the target platform supports native screens
Debugging
import { screensEnabled, freezeEnabled } from "react-native-screens";
// Debug current configuration
console.log("Screens enabled:", screensEnabled());
console.log("Freeze enabled:", freezeEnabled());Metro Configuration
Ensure proper Metro resolver configuration for react-native-screens:
// metro.config.js
module.exports = {
resolver: {
alias: {
'react-native-screens': require.resolve('react-native-screens'),
},
},
};Install with Tessl CLI
npx tessl i tessl/npm-react-native-screens