Skip to main content

​
Overview

Checks if a wake lock is currently held by this module. Useful for debugging or updating UI state based on wake lock status. 
function isWakeLockHeld(): Promise<boolean>

​
Returns

​
isHeld
boolean
Promise resolving to true if a wake lock is currently held, false otherwise.

​
Platform Behavior

PlatformBehavior
AndroidReturns whether a wake lock is actively held by this module. Checks the internal WakeLock.isHeld state.
iOSAlways returns false as wake locks don’t exist on iOS.

​
Use Cases

✅ Good use cases:
  • Checking if a wake lock is held before acquiring a new one
  • Updating UI to show active background tasks
  • Debugging wake lock state
  • Preventing duplicate wake lock acquisitions
  • Logging and analytics
❌ Not needed:
  • Before calling releaseWakeLock() (it’s safe to call even if not held)
  • For typical acquire/release patterns (just pair calls appropriately)

​
Example Usage

​
Check Before Acquiring

import { isWakeLockHeld, acquireWakeLock } from 'react-native-background-guardian';

const isHeld = await isWakeLockHeld();

if (!isHeld) {
  await acquireWakeLock('MyTask');
  console.log('Wake lock acquired');
} else {
  console.log('Wake lock already held');
}

​
Update UI State

import { useState, useEffect } from 'react';
import { isWakeLockHeld, acquireWakeLock, releaseWakeLock } from 'react-native-background-guardian';

function WakeLockIndicator() {
  const [isActive, setIsActive] = useState(false);

  useEffect(() => {
    const checkStatus = async () => {
      const held = await isWakeLockHeld();
      setIsActive(held);
    };

    // Check every 5 seconds
    const interval = setInterval(checkStatus, 5000);
    checkStatus();

    return () => clearInterval(interval);
  }, []);

  return (
    <View>
      <Text>Wake Lock: {isActive ? 'Active' : 'Inactive'}</Text>
    </View>
  );
}

​
Debugging Helper

import { isWakeLockHeld } from 'react-native-background-guardian';

async function debugWakeLockStatus() {
  const isHeld = await isWakeLockHeld();
  console.log('=== Wake Lock Status ===');
  console.log('Held:', isHeld);
  console.log('Timestamp:', new Date().toISOString());
}

// Call periodically or on specific events
debugWakeLockStatus();

​
Conditional Background Task

import { isWakeLockHeld, acquireWakeLock, releaseWakeLock } from 'react-native-background-guardian';

async function startBackgroundSync() {
  const alreadyRunning = await isWakeLockHeld();
  
  if (alreadyRunning) {
    console.log('Background sync already in progress');
    return;
  }

  await acquireWakeLock('BackgroundSync');
  
  try {
    await syncData();
  } finally {
    await releaseWakeLock();
  }
}

​
Status Display Component

import { View, Text, Button } from 'react-native';
import { isWakeLockHeld, acquireWakeLock, releaseWakeLock } from 'react-native-background-guardian';

function WakeLockControl() {
  const [isHeld, setIsHeld] = useState(false);

  const checkStatus = async () => {
    const held = await isWakeLockHeld();
    setIsHeld(held);
  };

  const handleAcquire = async () => {
    await acquireWakeLock('UserTask');
    await checkStatus();
  };

  const handleRelease = async () => {
    await releaseWakeLock();
    await checkStatus();
  };

  useEffect(() => {
    checkStatus();
  }, []);

  return (
    <View>
      <Text>Status: {isHeld ? '🟢 Held' : '⚪ Not Held'}</Text>
      <Button title="Acquire" onPress={handleAcquire} />
      <Button title="Release" onPress={handleRelease} />
    </View>
  );
}

​
Implementation Details

​
Android

On Android, this method checks the isHeld property of the PowerManager.WakeLock instance. It returns false if:
  • No wake lock has been acquired
  • The wake lock was released
  • The wake lock timed out

​
iOS

On iOS, this always returns false since the platform doesn’t support wake locks in the same way. iOS apps should use Background Modes configured in Xcode for background execution.