Documentation Index
Fetch the complete documentation index at: https://mintlify.com/ivangonzalezg/react-native-background-guardian/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Enables a screen wake lock to keep the display on while the app is in the foreground. This is different from CPU wake locks and does NOT keep background tasks running.
function enableScreenWakeLock(): Promise<boolean>
Returns
Promise resolving to true if the screen wake lock was enabled, false otherwise.
| Platform | Behavior |
|---|
| Android | Sets FLAG_KEEP_SCREEN_ON on the current Activity window. The screen stays on only while the app is visible. |
| iOS | Disables the idle timer (UIApplication.shared.isIdleTimerDisabled = true). The screen stays on while the app is active. |
Important Notes
- Foreground Only: This keeps the screen awake only while the app is in the foreground. It does NOT replace
acquireWakeLock() for background CPU execution.
- Activity Required: On Android, this requires a current Activity. Returns
false if no Activity is available.
- Battery Impact: Keeping the screen on consumes significant battery. Use sparingly and only when necessary.
- Automatic Cleanup: The system automatically clears this when the Activity is destroyed.
Use Cases
✅ Good use cases:
- Video playback
- Navigation/maps display
- Reading/viewing content
- Live monitoring dashboards
- Camera preview screens
❌ Not suitable for:
- Background task execution (use
acquireWakeLock() instead)
- When the app is in the background
- Battery-sensitive scenarios
Example Usage
Basic Usage
import { enableScreenWakeLock, disableScreenWakeLock } from 'react-native-background-guardian';
const enabled = await enableScreenWakeLock();
if (enabled) {
console.log('Screen will stay on');
}
// Later, when done
await disableScreenWakeLock();
Video Player Component
import { useEffect } from 'react';
import { enableScreenWakeLock, disableScreenWakeLock } from 'react-native-background-guardian';
import Video from 'react-native-video';
function VideoPlayer({ videoUrl }) {
useEffect(() => {
// Enable screen wake lock when video player mounts
enableScreenWakeLock();
// Disable when player unmounts
return () => {
disableScreenWakeLock();
};
}, []);
return (
<Video
source={{ uri: videoUrl }}
style={{ width: '100%', height: 300 }}
resizeMode="contain"
/>
);
}
Navigation Screen
import { useFocusEffect } from '@react-navigation/native';
import { enableScreenWakeLock, disableScreenWakeLock } from 'react-native-background-guardian';
function NavigationScreen() {
// Enable when screen is focused, disable when unfocused
useFocusEffect(
useCallback(() => {
enableScreenWakeLock();
return () => {
disableScreenWakeLock();
};
}, [])
);
return (
<MapView /* ... */ />
);
}
Conditional Screen Lock
import { useState } from 'react';
import { enableScreenWakeLock, disableScreenWakeLock } from 'react-native-background-guardian';
function ReadingScreen() {
const [keepScreenOn, setKeepScreenOn] = useState(false);
const toggleScreenLock = async () => {
if (keepScreenOn) {
await disableScreenWakeLock();
setKeepScreenOn(false);
} else {
const enabled = await enableScreenWakeLock();
setKeepScreenOn(enabled);
}
};
return (
<View>
<Switch
value={keepScreenOn}
onValueChange={toggleScreenLock}
/>
<Text>Keep Screen On</Text>
{/* Reading content */}
</View>
);
}
With Error Handling
import { enableScreenWakeLock, disableScreenWakeLock } from 'react-native-background-guardian';
const startPresentation = async () => {
const enabled = await enableScreenWakeLock();
if (!enabled) {
Alert.alert(
'Warning',
'Could not keep screen on. The screen may turn off during presentation.'
);
return;
}
// Show presentation
showPresentationSlides();
};
const endPresentation = async () => {
await disableScreenWakeLock();
console.log('Screen lock released');
};
Comparison with CPU Wake Lock
| Feature | enableScreenWakeLock() | acquireWakeLock() |
|---|
| Purpose | Keep screen on | Keep CPU running |
| Works when | App is visible | Background + foreground |
| Battery impact | High (screen on) | Medium (CPU running) |
| Use for | User-facing content | Background processing |
| iOS support | Yes (idle timer) | No (not applicable) |
