The documentation is currently a work in progress whilst the product is in alpha.

Appearance

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

Notifee 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.

Loading...
Android Text Styling Example

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

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

  • Using Android Studio, open your projects 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 the small icon, reference the name you provided whilst creating a notification, for example if created with the name ic_app_icon:

notifee.displayNotification({
  title: 'Small Icon',
  body: 'A notification using the small icon!.',
  android: {
    // Reference the name created
    smallIcon: 'ic_app_icon',
  },
});

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.

Loading...
Android Large Icon Example

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

  • Remote image URL.
  • Local image (e.g. require('./image.jpg')).
  • Android resources (checks mipmap first, then drawable).

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'),

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

Badges

Android devices on 8.0 (API level 26) and above have a feature called "notification badges". Badges are a way for users to interact with notifications without pulling down the notification shade, or opening the app. When enabled, your application icon will show a "notification dot" (see below) when there are unread notifications.

When a user long-presses on your application icon, the notification badge will appear with unread notification information:

Loading...
Android Badge Example

Since badges are only available on Android 8.0 and above, the devices will also have channel support. Using Notifee, there are two ways to control notification badges; via channels and on the notification.

When creating a channel, set the badge property to true or false to control whether notifications posted to the channel will appear in the badge if unread. This property defaults to true when creating a channel:

notifee.createChannel({
  id: 'messages',
  name: 'Private Messages',
  badge: false, // disable in badges
});

With channel badge support enabled, you can further choose how the icon appears inside of the badge. 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
NoneUses the default preference of the device launcher. Some launchers will display no icon, others will use the largeIcon (if provided).
SmallUses the icon provided to smallIcon, if available.
LargeUses the icon provided to largeIcon, if available.

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

import notifee, { AndroidBadgeIconType } from '@notifee/react-native';

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 own the notification shade. This level should only be used for urgent notifications, such as incoming phone calls, messages etc, which require immediate attention.

Loading...
Android High Importance Notification

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.

Loading...
Android Default Importance Notification

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.

Loading...
Android Low Importance Notification

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.

Loading...
Android Minimum Importance Notification

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 '@notifee/react-native';

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
PrivateShow the notification on all lockscreens, but conceal information on devices with secure lockscreens enabled.
PublicShow the notification in its entirety on all lockscreens.
SecretDo 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 '@notifee/react-native';

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.

Loading...
Android Red Colored Notification

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 '@notifee/react-native';

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

View the AndroidColor documentation for all available system colors.


Copyright 2020 © Invertase Limited

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License and code samples are licensed under the Apache 2.0 License.

All product names, logos, and brands are property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.