@gachlab/capacitor-dnd-plugin

A Capacitor plugin to detect and control Do Not Disturb (DND) mode.

| Platform | Detection | Control | |----------|-----------|---------| | Android | ✅ NotificationManager.getCurrentInterruptionFilter() | ✅ Requires ACCESS_NOTIFICATION_POLICY | | iOS | ⚠️ Heuristic via notification settings | ❌ Not allowed by iOS | | Web | ❌ Always returns false | ❌ Not supported |

Installation

npm install @gachlab/capacitor-dnd-plugin
npx cap sync

Usage

import { DoNotDisturb } from '@gachlab/capacitor-dnd-plugin';

// Check if DND is enabled
const { enabled } = await DoNotDisturb.isEnabled();
console.log('DND is', enabled ? 'on' : 'off');

// Listen for DND state changes
await DoNotDisturb.addListener('dndStateChanged', (state) => {
  console.log('DND changed:', state.enabled);
});

// Enable DND (Android only)
await DoNotDisturb.setEnabled({ enabled: true });

// Disable DND (Android only)
await DoNotDisturb.setEnabled({ enabled: false });

API

isEnabled()

isEnabled() => Promise<{ enabled: boolean }>

Returns the current Do Not Disturb state.

setEnabled(options)

setEnabled(options: { enabled: boolean }) => Promise<void>

Enables or disables Do Not Disturb mode. Only supported on Android. Requires ACCESS_NOTIFICATION_POLICY permission — the user must grant this manually in system settings.

Rejects with an error on iOS and Web.

addListener('dndStateChanged', ...)

addListener(
  eventName: 'dndStateChanged',
  listenerFunc: (state: { enabled: boolean }) => void,
) => Promise<PluginListenerHandle>

Listens for changes to the DND state. On Android, this uses a BroadcastReceiver. On iOS, the state is re-checked each time the app returns to the foreground (UIApplication.didBecomeActiveNotification / willEnterForegroundNotification) — iOS does not provide a system-level DND/Focus change event, so background toggles are not observed in real time.

removeAllListeners()

removeAllListeners() => Promise<void>

Removes all event listeners for this plugin.

Platform Notes

Android

Requires ACCESS_NOTIFICATION_POLICY permission. The user must manually enable "Do Not Disturb access" for your app in system settings. The setEnabled() method will reject if this permission is not granted.

iOS

Apple does not provide a public API to read or control Focus/DND state. This plugin uses a heuristic: if notifications are authorized but alerts are disabled, DND is likely active. This is not 100% reliable. setEnabled() always rejects on iOS.

State changes are detected when the app returns to the foreground, not while it is backgrounded — there is no iOS notification for DND/Focus toggles. If you need the freshest value at a specific moment (e.g. on a screen mount), call isEnabled() directly rather than relying on the event.

Migration from v1

v2 introduces breaking changes to the API:

- const { enabled } = await DoNotDisturb.monitor();
+ const { enabled } = await DoNotDisturb.isEnabled();

- await DoNotDisturb.set({ enabled: true });
+ await DoNotDisturb.setEnabled({ enabled: true });

- DoNotDisturb.addListener('monitor', callback);
+ DoNotDisturb.addListener('dndStateChanged', callback);