title	Appearance
description	Notifications can be displayed to your users in a variety of ways.

This page covers how to customise the appearance of notifications. Whilst changing the appearance can improve the overall aesthetics of a notification, it isn't required. A notification will simply use default appearance attributes.

Text Styling

Notify Kit supports basic HTML attributes for the majority of text properties, allowing you to customize the appearance of notifications. It is possible to change the text color, font weight and add unicode characters.

The code for the example video:

notifee.displayNotification({
  title: '<p style="color: #4caf50;"><b>Styled HTMLTitle</span></p></b></p> &#128576;',
  subtitle: '&#129395;',
  body: 'The <p style="text-decoration: line-through">body can</p> also be <p style="color: #ffffff; background-color: #9c27b0"><i>styled too</i></p> &#127881;!',
  android: {
    channelId,
    color: '#4caf50',
    actions: [
      {
        title: '<b>Dance</b> &#128111;',
        pressAction: { id: 'dance' },
      },
      {
        title: '<p style="color: #f44336;"><b>Cry</b> &#128557;</p>',
        pressAction: { id: 'cry' },
      },
    ],
  },
});

Any unsupported HTML attributes will be automatically removed from the body.

Icons

Notifications can be shown with two types of icons; small & large. Each icon type has a different purpose as outlined below.

Small Icons

Small Icons are primarily used for users to identify your app, typically matching your app's logo. Alternatively, they can be used to reflect the content type of the notification. For example, Google uses a TV icon to represent notifications about Films and TV Shows.

The small icon must have a transparent background, otherwise Android will display a solid square.

To create a small icon, you must add the resource directly from Android studio, which will take care of device compatibility and format:

Using Android Studio, open your project's android directory.
Open the app/main directory in the file tree.
Right click on the main directory & select New -> Image Asset.
Select the "Notification Icons" icon type, and follow the wizard by creating your new icon.
Once finished, Android Studio will inject multiple icon files into your projects resource (res) directory.

To set a small icon, add a smallIcon property to the notification body:

notifee.displayNotification({
  title: 'Small Icon',
  body: 'A notification using the small icon!.',
  android: {
    // Reference the name created (Optional, defaults to 'ic_launcher')
    smallIcon: 'ic_small_icon',

    // Set color of icon (Optional, defaults to white)
    color: '#9c27b0',
  },
});

Note (from 10.1.0): if the smallIcon name cannot be resolved at runtime (asset missing from release builds, R8 resource shrinking, naming mismatch), the library falls back to your app's launcher icon and logs a warning at level w instead of failing the notification display. See the README Troubleshooting section for diagnosis tips.

The image file used in the example can be downloaded here.

Large Icons

Large icons are used to give a notification additional context, for example showing the avatar of the user sending you a message. The large icon will be shown in different places by the device depending on the notification configuration.

There are a number of different ways to display a large icon:

Remote image URL.
Local image (e.g. require('./image.jpg')).
Absolute file path (e.g. file:///xxxx/xxxx/xxxx.jpg).
Android resources (checks mipmap first, then drawable - Note there appears to be an Android limitation where if the mipmap folder contains any xml files, the icon will not load).

The image will be automatically scaled to fit inside of the notification. It is recommended you use images a minimum size of 192x192 pixels to handle all device resolutions.

To set a large icon, add a largeIcon property to the notification body:

notifee.displayNotification({
  title: 'Chat with Joe Bloggs',
  body: 'A new message has been received from a user.',
  android: {
    // Remote image
    largeIcon: 'https://my-cdn.com/users/123456.png',

    // Local image
    largeIcon: require('../assets/user.jpg'),

    // Absolute file path
    largeIcon: file:///xxxx/xxxx/xxxx.jpg,

    // Android resource (mipmap or drawable)
    largeIcon: 'large_icon',

    // Base 64 image
    largeIcon: `data:${image.mime};base64,${image.rawBase64Data}`
  },
});

Badges

Devices running Android 8.0 (API level 26) and above support channel-based notification badges and dots. On launchers that support them, these surfaces let users interact with notifications without pulling down the notification shade or opening the app. Their appearance is controlled by the launcher and device manufacturer (OEM): some launchers may show a number, others may show only a notification dot, and launchers may aggregate notifications differently. A number on the app icon is therefore not guaranteed.

On compatible launchers, long-pressing the application icon may show unread notification information:

On Android 8.0 and above, a channel controls whether its notifications can contribute to badging on systems that support it. Set the channel's badge property to true to allow this. The property defaults to true when creating a channel, and it does not set a count:

await notifee.createChannel({
  id: 'messages',
  name: 'Private Messages',
  badge: true,
});

You cannot update the badge property value once the channel has been created.

Set android.badgeCount to associate a number with an individual notification. Notify Kit applies this using the Android behavior corresponding to NotificationCompat.Builder.setNumber(...). The notification number itself is not restricted to API level 26; that requirement applies to channel-based notification badges and dots.

await notifee.displayNotification({
  id: 'messages',
  title: 'New messages',
  body: 'You have 5 unread messages',
  android: {
    channelId: 'messages',
    badgeCount: 5,
  },
});

To update the number on an existing notification, display it again with the same id and a new badgeCount. Android will update or replace that notification. The launcher may use the notification number when representing it on the app icon, but the numeric rendering and aggregation remain launcher- and OEM-dependent.

On iOS, notifee.setBadgeCount() controls the global badge on the app icon. Android has no equivalent standard public API for setting a global app icon badge independently of notifications, so android.badgeCount is not its global equivalent. In particular, badgeCount: 0 does not provide a portable equivalent of await notifee.setBadgeCount(0): the Android notification remains posted and there is no portable global badge count to clear.

With channel badge support enabled, you can further choose which notification icon appears in the badge surface. The example image above shows the notification large icon being displayed.

To control what icon is used on the badge, the badgeIconType property on the notification body can be set. This property accepts one of three types:

Type
None	Uses the default preference of the device launcher. Some launchers will display no icon, others will use the `largeIcon` (if provided).
Small	Uses the icon provided to `smallIcon`, if available.
Large	Uses the icon provided to `largeIcon`, if available.

The default type used is "Large". To use a different type:

import notifee, { AndroidBadgeIconType } from 'react-native-notify-kit';

notifee.displayNotification({
  body: 'Notification using small icon in badged mode',
  android: {
    channelId, // channel with badges enabled
    badgeIconType: AndroidBadgeIconType.SMALL,
  },
});

Importance

The importance of a notification changes how it is presented to users. Notifications can be assigned an importance via the channel for devices on Android 8.0 (API Level 26) and above, or directly on the notification for devices without channel support.

See below to see how to set an importance level.

Levels

There are five types of importance levels which can be used to display a notification.

High

The highest importance level applied to a channel/notification. Notifications will appear on-top of applications, allowing direct interaction without pulling down the notification shade. This level should only be used for urgent notifications, such as incoming phone calls, messages etc, which require immediate attention.

Default

When no importance has been assigned, the default will be used. When a notification is received, the device smallIcon will appear in the notification shade. When the user pulls down the notification shade, the content of the notification will be shown in it's expanded state.

Low

A low importance level applied to a channel/notification. The application small icon will show in the device status bar, however the notification will not alert the user (no sound or vibration). The notification will show in it's expanded state when the notification shade is pulled down.

Minimum

The minimum importance level applied to a channel/notification. The application small icon will not show up in the status bar, or alert the user. The notification will be in a collapsed state in the notification shade and placed at the bottom of the list.

None

The notification will not be shown. This has the same effect as the user disabling notifications in the application settings.

Setting importance level

You should always choose an appropriate importance level for the type of notification. Showing an irrelevant or meta notification (e.g. recommended content) at high importance will more than likely cause the user to disable notifications for your entire application.

On devices with channel support, the importance is set on the channel. On devices without channel support, the importance can be set directly on the notification:

import notifee, { AndroidImportance } from 'react-native-notify-kit';

const channelId = await notifee.createChannel({
  id: 'important',
  name: 'Important Notifications',
  importance: AndroidImportance.HIGH,
});

await notifee.displayNotification({
  title: 'Your account requires attention',
  body: 'You are overdue payment on one or more of your accounts!',
  android: {
    channelId,
    importance: AndroidImportance.HIGH,
  },
});

If your application does not target devices lower than Android 8.0 (API Level 26), you can omit the importance property from the notification body.

Visibility

Controlling the visibility of a notification on the users device is important, especially if a notification contains sensitive information (such as a banking app). Setting the visibility controls how a notification is shown to a locked device on the lockscreen.

There are three types of visibilities:

Type
Private	Show the notification on all lockscreens, but conceal information on devices with secure lockscreens enabled.
Public	Show the notification in its entirety on all lockscreens.
Secret	Do not reveal/show any part of this notification on a secure lockscreen.

The default visibility is Private.

On devices with channel support, the visibility is set on the channel. On devices without channel support, the visibility can be set directly on the notification:

import notifee, { AndroidVisibility } from 'react-native-notify-kit';

const channelId = await notifee.createChannel({
  id: 'secret',
  name: 'Secret Notifications',
  visibility: AndroidVisibility.SECRET,
});

await notifee.displayNotification({
  title: 'Your payment information',
  body: 'A payment has been made to another account',
  android: {
    channelId,
    visibility: AndroidVisibility.SECRET,
  },
});

If your application does not target devices lower than Android 8.0 (API Level 26), you can omit the visibilty property from the notification body.

View the AndroidVisibility documentation for more information.

Color

Notifications can be colored to match with your application theme. A single color can be used and will be automatically applied by the system.

The device uses the color to change various parts of the notification:

Tinting the small icon.
Setting text color on notification action text.
Tinting the progress bar color when using progress indicators.
Setting the background color of a notification input box.
Changing the background color of the entire notification when used with Foreground Services.

You can use system colors, or a custom hexadecimal color, for example:

import notifee, { AndroidColor } from 'react-native-notify-kit';

notifee.displayNotification({
  android: {
    color: AndroidColor.RED,
    // or
    color: '#E8210C', // red
  },
});

View the AndroidColor documentation for all available system colors.

FilesExpand file tree

appearance.mdx

Latest commit

History