Appearance

Attachments

Using the attachments property on a notification, you can attach a media file which can be viewed when the user expands the notification or as a thumbnail on the notification itself.

When a notification is collapsed, a thumbnail will be shown in the notification, unless thumbnailHidden is set to true.

Only a single media file can be shown on the notification, if you provide many then the first attachment that can be successfully resolved will be displayed.

To add attachments, provide an attachments array to the ios object:

import notifee from 'react-native-notify-kit';

notifee.displayNotification({
  title: 'Media uploaded',
  body: 'Your media has been successfully uploaded',
  ios: {
    attachments: [
      {
        // iOS resource
        url: 'local-image.png',
        thumbnailHidden: true,
      },
      {
        // Local file path.
        url: '/Path/on/device/to/local/file.mp4',
        thumbnailTime: 3, // optional
      },
      {
        // React Native asset.
        url: require('./assets/my-image.gif'),
      },
      {
        // Remote image
        url: 'https://my-cdn.com/images/123456.png',
      },
    ],
  },
});

Audio, image and video files are supported.

Advanced attachment options — typeHint (the Uniform Type Identifier, e.g. 'public.jpeg', used when iOS can't infer the content type from the URL) and thumbnailClippingRect (to crop the thumbnail shown when the notification is collapsed) — are documented in the IOSNotificationAttachment reference along with every available field.

Foreground Notifications

By default, Notify Kit will show iOS notifications in heads-up mode if your app is currently in the foreground.

This behaviour can be customised using the IOSForegroundPresentationOptions options:

import notifee from 'react-native-notify-kit';

await notifee.displayNotification({
  title: 'Your account requires attention',
  body: 'You are overdue payment on one or more of your accounts!',
  ios: {
    foregroundPresentationOptions: {
      badge: true,
      sound: true,
      banner: true,
      list: true,
    },
  },
});

Summary text

After a number of unread notifications have been delivered to the device, iOS will begin to stack (or group) notifications for your application. The notification on the top of the stack by default will display the summary text, letting the user know how many unread notifications are available:

You can customize category summary text with a Category summaryFormat.

The legacy summaryArgument and summaryArgumentCount notification fields are kept for compatibility, but they are no-ops on supported iOS versions because Apple ignores notification summary arguments on iOS 15+. They may be removed in a future major release, so avoid relying on them for summary text.

To learn more, view the Category Summary Text documentation.

This functionality is only available on iOS >= 12.