react-native-nitro-notification

A high-performance React Native remote push notification library built on NitroModules.

Platform support: iOS only. Android support is not yet implemented.

Installation

pnpm add react-native-nitro-notification
npx pod-install

iOS setup

The library needs to receive the APNs device token from your app delegate. Add the following to your AppDelegate:

import NitroNotification

func application(
  _ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
  NotificationCenter.default.post(
    name: NitroNotificationTokenNotification,
    object: nil,
    userInfo: [NitroNotificationTokenKey: deviceToken]
  )
}

No other app delegate changes are required. The library registers itself as a UNUserNotificationCenterDelegate automatically at load time.

Usage

Request permissions

import { Notifications } from 'react-native-nitro-notification';

const status = await Notifications.requestPermissions({
  alert: true,
  sound: true,
  badge: true,
});
// status: 'granted' | 'denied' | 'undetermined' | 'provisional'

Get current permission status

const status = await Notifications.getPermissionStatus();

Get the APNs push token

requestPermissions automatically registers for remote notifications on success, so the token is available immediately after a 'granted' or 'provisional' result.

const token = await Notifications.getDevicePushToken();

Unregister from remote notifications

await Notifications.unregisterForNotifications();

Listen for events

// Token refreshed
const sub = Notifications.addOnTokenRefreshed((token) => {
  console.log('New token:', token);
});

// Notification tapped
const sub = Notifications.addOnNotificationTapped((response) => {
  console.log('Tapped:', response.notification.title);
  console.log('Action:', response.actionIdentifier);
});

// Clean up
sub.remove();

Handle taps when the app was closed

addOnNotificationTapped only fires for listeners that exist when the tap arrives. When a tap launches the app from a killed state, your JS listener is not registered yet, so the event is lost. The library keeps the most recent tap natively so you can read it on startup:

// Run once the navigation is ready
const response = Notifications.getLastNotificationResponse();
if (response) {
  navigateTo(response);
  Notifications.clearLastNotificationResponse();
}

Only the most recent tap is stored. Call clearLastNotificationResponse after handling it, otherwise the same tap is returned again the next time you read it (for example after a JS reload).

On Android, getLastNotificationResponse currently always returns undefined.

Handle foreground notifications

By default, foreground notifications are presented with alert, badge, and sound. Use setNotificationHandler to control presentation per notification:

Notifications.setNotificationHandler(async (notification) => {
  console.log('Received in foreground:', notification.title);
  return { alert: true, badge: true, sound: false };
});

// Clear the handler
Notifications.setNotificationHandler(undefined);

The handler has a default timeout of 5000 ms. If it rejects or times out, the notification falls back to showing alert, badge, and sound.

// Custom timeout
Notifications.setNotificationHandler(async (notification) => {
  return { alert: true, badge: false, sound: true };
}, 3000);

Notification categories and actions

Register categories to attach action buttons (and inline text replies) to notifications. A notification uses a category when its push payload has a matching categoryIdentifier.

await Notifications.setNotificationCategories([
  {
    identifier: 'message',
    actions: [
      {
        identifier: 'reply',
        buttonTitle: 'Reply',
        textInput: { submitButtonTitle: 'Send', placeholder: 'Write a reply' },
      },
      {
        identifier: 'delete',
        buttonTitle: 'Delete',
        options: { isDestructive: true, opensAppToForeground: false },
      },
    ],
  },
]);

Notifications.addOnNotificationTapped((response) => {
  if (response.actionIdentifier === 'reply') {
    console.log('Reply text:', response.userText);
  }
});

setNotificationCategories replaces the full set of registered categories. Calling it again removes any category that is not in the new array, so always pass every category your app needs.

On Android this method currently rejects with an UnsupportedOperationException.

API

Notifications

Method	Description
requestPermissions(options?)	Prompts the user for notification permissions. Returns the resulting PermissionStatus. On success, also calls registerForRemoteNotifications() so the push token is immediately available.
getPermissionStatus()	Returns the current PermissionStatus without prompting.
getDevicePushToken()	Registers for remote notifications and resolves with the APNs device token as a hex string.
unregisterForNotifications()	Unregisters from remote notifications on the device.
setNotificationHandler(handler, timeoutMs?)	Sets a callback invoked when a notification arrives while the app is in the foreground. The handler returns NotificationPresentationOptions to control how the notification is shown. Pass undefined to clear the handler.
setNotificationCategories(categories)	Registers the notification categories and their actions. Replaces all previously registered categories. Rejects on Android.
addOnTokenRefreshed(listener)	Subscribes to push token refresh events. Returns a ListenerSubscription.
addOnNotificationTapped(listener)	Subscribes to notification tap events. Returns a ListenerSubscription.
getLastNotificationResponse()	Synchronously returns the most recent NotificationResponse, or undefined if there is none. Use it on startup to recover a tap that launched the app from a killed state. Always undefined on Android.
clearLastNotificationResponse()	Clears the stored response so it is not returned again.

PermissionStatus

Value	Description
'granted'	The user has authorized notifications.
'denied'	The user has denied notifications.
'undetermined'	The user has not yet been asked.
'provisional'	Provisional authorization (iOS) -- notifications deliver silently to Notification Center without a prompt.

RequestPermissionsOptions

All fields are iOS-specific. On Android, this object is accepted but ignored.

Property	Type	Default	Description
alert	boolean?	true	Show notification banners and Notification Center entries.
sound	boolean?	true	Play a sound when a notification is delivered.
badge	boolean?	true	Update the app icon badge number.
carPlay	boolean?	false	Display notifications in CarPlay.
criticalAlert	boolean?	false	Play sound even when muted or Do Not Disturb is on. Requires an Apple entitlement.
providesAppNotificationSettings	boolean?	false	Show a link to your in-app notification settings from the system settings page.
provisional	boolean?	false	Request provisional authorization -- no prompt shown to the user.

NotificationPayload

Property	Type	Description
title	string?	Notification title.
body	string?	Notification body.
data	Record<string, string>?	Custom key-value payload.
badge	number?	Badge count included in the payload.

NotificationResponse

Received in addOnNotificationTapped callbacks and returned by getLastNotificationResponse.

Property	Type	Description
notification	NotificationPayload	The notification that was tapped.
actionIdentifier	string	The identifier of the action that was invoked (e.g. UNNotificationDefaultActionIdentifier for a plain tap).
userText	string?	Text typed by the user when the action has a textInput. Undefined otherwise or when the field is empty.

NotificationCategory

Property	Type	Description
identifier	string	Matches the categoryIdentifier field in the push payload.
actions	NotificationAction[]	Actions shown on notifications of this category.
options	NotificationCategoryOptions?	iOS-specific category options.

NotificationCategoryOptions

All fields are iOS only.

Property	Type	Description
previewPlaceholder	string?	Body placeholder shown when the user has hidden previews.
intentIdentifiers	string[]?	Siri intent class identifiers associated with the category.
categorySummaryFormat	string?	Format string for the grouped notification summary.
customDismissAction	boolean?	Notify the app when the user explicitly dismisses the notification.
allowInCarPlay	boolean?	Allow the actions to appear in CarPlay.
showTitle	boolean?	Show the title even when the user has hidden previews.
showSubtitle	boolean?	Show the subtitle even when the user has hidden previews.

NotificationAction

Property	Type	Description
identifier	string	Delivered back in NotificationResponse.actionIdentifier.
buttonTitle	string	Label shown on the action button.
textInput	NotificationTextInput?	When present, the action becomes an inline text reply field.
options	NotificationActionOptions?	Action behavior options.

NotificationActionOptions

Property	Type	Default	Description
isDestructive	boolean?	false	Render the button in a destructive style. iOS only.
isAuthenticationRequired	boolean?	false	Require device authentication before the action fires. iOS only.
opensAppToForeground	boolean?	true	Bring the app to the foreground when the action is triggered.

NotificationTextInput

Property	Type	Description
submitButtonTitle	string	Title of the submit button. iOS only.
placeholder	string	Placeholder shown before the user starts typing.

NotificationPresentationOptions

Returned by the NotificationHandler to control foreground presentation.

Property	Type	Description
alert	boolean	Show the notification banner.
badge	boolean	Update the app icon badge.
sound	boolean	Play the notification sound.

NotificationHandler

type NotificationHandler = (notification: NotificationPayload) => Promise<NotificationPresentationOptions>;

ListenerSubscription

interface ListenerSubscription {
  remove: () => void;
}

License

MIT