expo-notifications

Fetch push tokens, present notifications, schedule local notifications, and handle responses

expo-notifications

Version: 55.0.7

Provides an API to fetch push notification tokens and to present, schedule, receive, and respond to notifications. Supports both local and remote push notifications.

Installation

npx expo install expo-notifications

Usage

import * as Notifications from 'expo-notifications';

// Configure notification behavior
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: false,
  }),
});

// Request permissions
const { status } = await Notifications.requestPermissionsAsync();

// Get push token
const token = (await Notifications.getExpoPushTokenAsync()).data;

// Schedule local notification
await Notifications.scheduleNotificationAsync({
  content: {
    title: 'Hello!',
    body: 'This is a notification',
  },
  trigger: {
    seconds: 5,
  },
});

// Listen for notifications
Notifications.addNotificationReceivedListener((notification) => {
  console.log('Notification received:', notification);
});

Notifications.addNotificationResponseReceivedListener((response) => {
  console.log('Notification tapped:', response);
});

API Reference

Permissions

requestPermissionsAsync(request) · (request?: NotificationPermissionsRequest) => Promise<NotificationPermissionsStatus>

Requests notification permissions

const { status } = await Notifications.requestPermissionsAsync({
  ios: {
    allowAlert: true,
    allowBadge: true,
    allowSound: true,
  },
});

getPermissionsAsync() · () => Promise<NotificationPermissionsStatus>

Gets current permission status

Push Tokens

getExpoPushTokenAsync(options) · (options?: ExpoPushTokenOptions) => Promise<ExpoPushToken>

Gets Expo push token

const token = await Notifications.getExpoPushTokenAsync({
  projectId: 'your-project-id',
});
console.log('Token:', token.data);

getDevicePushTokenAsync() · () => Promise<DevicePushToken>

Gets native device push token (FCM/APNs)

Local Notifications

scheduleNotificationAsync(request) · (request: NotificationRequestInput) => Promise<string>

Schedules a local notification

const id = await Notifications.scheduleNotificationAsync({
  content: {
    title: 'Reminder',
    body: 'Don\'t forget!',
    data: { customData: 'value' },
  },
  trigger: {
    seconds: 10,
  },
});

presentNotificationAsync(content) · (content: NotificationContentInput) => Promise<string>

Shows notification immediately

await Notifications.presentNotificationAsync({
  title: 'Now',
  body: 'Immediate notification',
});

cancelScheduledNotificationAsync(identifier) · (identifier: string) => Promise<void>

Cancels scheduled notification

cancelAllScheduledNotificationsAsync() · () => Promise<void>

Cancels all scheduled notifications

getAllScheduledNotificationsAsync() · () => Promise<Notification[]>

Gets all scheduled notifications

Notification Management

dismissNotificationAsync(identifier) · (identifier: string) => Promise<void>

Dismisses displayed notification

dismissAllNotificationsAsync() · () => Promise<void>

Dismisses all displayed notifications

getPresentedNotificationsAsync() · () => Promise<Notification[]>

Gets currently displayed notifications

Badge Count

setBadgeCountAsync(count) · (count: number) => Promise<boolean>

Sets app badge count

await Notifications.setBadgeCountAsync(5);

getBadgeCountAsync() · () => Promise<number>

Gets current badge count

Event Listeners

addNotificationReceivedListener(listener) · (listener: (notification: Notification) => void) => Subscription

Listens for received notifications

const subscription = Notifications.addNotificationReceivedListener(
  (notification) => {
    console.log('Received:', notification.request.content.title);
  }
);

addNotificationResponseReceivedListener(listener) · (listener: (response: NotificationResponse) => void) => Subscription

Listens for notification taps

Notifications.addNotificationResponseReceivedListener((response) => {
  const data = response.notification.request.content.data;
  // Navigate based on data
});

Configuration

setNotificationHandler(handler) · (handler: NotificationHandler | null) => void

Configures notification behavior

Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: true,
    priority: Notifications.AndroidNotificationPriority.HIGH,
  }),
});

setNotificationChannelAsync(identifier, channel) · (identifier: string, channel: NotificationChannel) => Promise<NotificationChannel | null>

Creates/updates Android notification channel

await Notifications.setNotificationChannelAsync('default', {
  name: 'Default',
  importance: Notifications.AndroidImportance.HIGH,
  vibrationPattern: [0, 250, 250, 250],
  sound: 'notification.wav',
});

Examples

Complete Setup

import * as Notifications from 'expo-notifications';
import { useState, useEffect, useRef } from 'react';
import { Platform } from 'react-native';

// Configure handler
Notifications.setNotificationHandler({
  handleNotification: async () => ({
    shouldShowAlert: true,
    shouldPlaySound: true,
    shouldSetBadge: false,
  }),
});

export default function App() {
  const [pushToken, setPushToken] = useState('');
  const notificationListener = useRef<Notifications.Subscription>();
  const responseListener = useRef<Notifications.Subscription>();

  useEffect(() => {
    registerForPushNotifications();

    // Add listeners
    notificationListener.current = Notifications.addNotificationReceivedListener(
      (notification) => {
        console.log('Notification received:', notification);
      }
    );

    responseListener.current = Notifications.addNotificationResponseReceivedListener(
      (response) => {
        console.log('Notification tapped:', response);
      }
    );

    return () => {
      notificationListener.current?.remove();
      responseListener.current?.remove();
    };
  }, []);

  async function registerForPushNotifications() {
    const { status: existingStatus } = await Notifications.getPermissionsAsync();
    let finalStatus = existingStatus;

    if (existingStatus !== 'granted') {
      const { status } = await Notifications.requestPermissionsAsync();
      finalStatus = status;
    }

    if (finalStatus !== 'granted') {
      alert('Failed to get push token');
      return;
    }

    const token = (await Notifications.getExpoPushTokenAsync()).data;
    setPushToken(token);

    // Send token to your server
    await sendTokenToServer(token);

    // Android channel
    if (Platform.OS === 'android') {
      Notifications.setNotificationChannelAsync('default', {
        name: 'default',
        importance: Notifications.AndroidImportance.MAX,
      });
    }
  }

  // Rest of component...
}

Schedule Notification

import * as Notifications from 'expo-notifications';

async function scheduleReminder() {
  await Notifications.scheduleNotificationAsync({
    content: {
      title: 'Reminder',
      body: 'Time to check your tasks',
      data: { screen: 'tasks' },
    },
    trigger: {
      hour: 9,
      minute: 0,
      repeats: true,
    },
  });
}

Handle Notification Tap

import * as Notifications from 'expo-notifications';
import { useNavigation } from '@react-navigation/native';

function useNotifications() {
  const navigation = useNavigation();

  useEffect(() => {
    const subscription = Notifications.addNotificationResponseReceivedListener(
      (response) => {
        const { screen } = response.notification.request.content.data;
        
        if (screen) {
          navigation.navigate(screen as never);
        }
      }
    );

    return () => subscription.remove();
  }, []);
}

Platform Support

Platform	Supported
iOS	✅
Android	✅
Web	✅ (Limited)

Configuration

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-notifications",
        {
          "icon": "./assets/notification-icon.png",
          "color": "#ffffff",
          "sounds": ["./assets/notification.wav"]
        }
      ]
    ],
    "notification": {
      "icon": "./assets/notification-icon.png",
      "color": "#ffffff"
    }
  }
}

Permissions

iOS: Add to app.json:

{
  "ios": {
    "infoPlist": {
      "UIBackgroundModes": ["remote-notification"]
    }
  }
}

Android: Permissions automatically added.

Best Practices

1. Request Permissions: Always request before sending notifications
2. Configure Handler: Set notification handler before listeners
3. Clean Up: Remove listeners in component cleanup
4. Android Channels: Create channels for Android 8+
5. Error Handling: Handle permission denials gracefully

On iOS, notifications may not appear when app is in foreground unless configured in notification handler.

Resources

• Official Documentation
• GitHub Repository
• Push Notification Tool