---
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:
```js
notifee.displayNotification({
title: 'Styled HTMLTitle
🙀',
subtitle: '🥳',
body: 'The body can
also be styled too
🎉!',
android: {
channelId,
color: '#4caf50',
actions: [
{
title: 'Dance 👯',
pressAction: { id: 'dance' },
},
{
title: 'Cry 😭
',
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.
#### Bare React Native
For a bare React Native project, add the resource through Android Studio, which will take care of device compatibility and format:
1. Using Android Studio, open your project's `android` directory.
2. Open the `app/main` directory in the file tree.
3. Right click on the `main` directory & select `New -> Image Asset`.
4. Select the "Notification Icons" icon type, and follow the wizard by creating your new icon.
5. Once finished, Android Studio will inject multiple icon files into your projects resource (`res`) directory.
The image file used in the example can be downloaded [here](https://user-images.githubusercontent.com/14185925/86519462-cde1f000-be32-11ea-8ae6-cdec95754866.png).
#### Expo CNG / prebuild
For Expo CNG/prebuild projects, configure the NotifyKit config plugin to generate the Android resources during prebuild instead of editing the generated `android/app/src/main/res` directory:
```ts
// app.config.ts
export default {
expo: {
plugins: [
[
'react-native-notify-kit',
{
android: {
icons: [
{
name: 'notification_message',
path: './assets/notification-message.png',
type: 'small',
},
],
},
},
],
],
},
};
```
Each `android.icons` entry generates PNG drawables with a transparent background and `cover` resizing:
| Resource folder | Size |
| ------------------ | ----- |
| `drawable-mdpi` | 24×24 |
| `drawable-hdpi` | 36×36 |
| `drawable-xhdpi` | 48×48 |
| `drawable-xxhdpi` | 72×72 |
| `drawable-xxxhdpi` | 96×96 |
The source must be a PNG at a project-relative path inside the project root. The Android resource `name` must start with a lowercase letter and then contain only `a-z`, `0-9`, or `_`; invalid names are rejected during configuration/prebuild rather than normalized. The array supports multiple icons and preserves their order. Each entry must include `type: 'small'`; omitting it or using another type fails during configuration/prebuild. The config plugin also writes an Android resource-shrinker keep rule for the generated icons.
This option generates resources only. It does not set an icon on notifications and does not configure Firebase's `com.google.firebase.messaging.default_notification_icon` metadata.
#### Use the resource name
Set `android.smallIcon` to the configured Android resource `name`, not the source file path:
```ts
await notifee.displayNotification({
title: 'New message',
android: {
channelId: 'messages',
smallIcon: 'notification_message',
},
});
```
**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](https://github.com/marcocrupi/react-native-notify-kit#small-icon-not-showing-in-android-release-builds-falls-back-to-launcher-icon) for diagnosis tips.
### 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:
```js
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](/react-native/android/channels) 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:
```js
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.
```js
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:
```js
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](/react-native/android/channels) support, the importance is set on the channel. On devices
without channel support, the importance can be set directly on the notification:
```js
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](/react-native/android/channels) support, the visibility is set on the channel. On devices
without channel support, the visibility can be set directly on the notification:
```js
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`](/react-native/reference/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](/react-native/android/progress-indicators).
- Setting the background color of a notification input box.
- Changing the background color of the entire notification when used with [Foreground Services](/react-native/android/foreground-service).
You can use system colors, or a custom hexadecimal color, for example:
```js
import notifee, { AndroidColor } from 'react-native-notify-kit';
notifee.displayNotification({
android: {
color: AndroidColor.RED,
// or
color: '#E8210C', // red
},
});
```
View the [`AndroidColor`](/react-native/reference/androidcolor) documentation for all available system colors.