OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Web Push Notification Icons

Customizing Web Push notifications with your app icons, colors, and style.

Web push notifications support icon, image, and badge customization options.

Setting the Icon, Image, and Badge

On the dashboard, the icon, image, and badge can be set here:

Sending from API, use chrome_web_icon, chrome_web_image, and chrome_web_badge parameters

As of with Chrome 59, big pictures are no longer supported on MacOS. Badges are only supported on Chrome on Android 53+.


The icon displays to the side of the notification's title and message. In this example, it is the OneSignal logo:

Icon Requirements


RGB colors


192x192 or larger


jpg, png, gif, webp, ico, cur, bmp

Not supported: svg or gif animations.


Chrome (on Windows Desktop and Android) supports displaying a large image below the notification's title and message:

Keep in mind:

On Chrome (Windows only):

  • Chrome 68+ : The image should be at least 360x180 or have a 2:1 aspect ratio.
  • Chrome 67 and lower: The image should be at least 360x240, with a 1.5 aspect ratio. We recommend 720x480 to make images look best for users with HiDPI (retina) displays.
  • Smaller images will be upscaled to fit the container while preserving the aspect ratio; larger images will be downscaled
  • The image is displayed using 'contain' sizing: each side of the image is as large as possible while not exceeding the the container side's length

On Chrome on Android:

  • The image is displayed using 'cover' sizing: the image covers the container entirely, even it means cropping the top/bottom or sides of the images
  • If the notification tray has too many notifications, the image will not be displayed by default, and the user must "scroll down" on the notification to see it. Examples are below.
  • Use a 2:1 aspect ratio. Android not have a size limit, but we recommend:
    • Minimum - 512x256
    • Balanced - 1024x512
    • Maximum - 2048x1024

Platform size example are below.

Chrome Desktop Image Examples

360 x 240: 1.5 Aspect Ratio

Note: we recommend 720x480 to make images look best for users with HiDPI (retina) displays.

90 x 60: 1.5 Aspect Ratio

360 x 120: 3 Aspect Ratio

180 x 240: 0.75 Aspect Ratio

80 x 80: 1 Aspect Ratio

Chrome on Android Image Examples

500x500 x : 1 Aspect Ratio

Because of 'cover' sizing, a 500x500 image fills up the viewport:

Desktop vs. Android 500x500 Same Image

Comparing the difference between the 'contain' and 'cover' sizing in Desktop vs. Android using the same image:

Sliding Image on Android (too many notifications in tray)

When there are too many notifications in the tray, your image may not be shown at first. The notification has to be "scrolled down" to see the image:


For Chrome 53+ on Android 6.0+, the badge replaces the Chrome browser icon that appears on the notification tray and above the title. In this example, a custom badge for the app replaces the Chrome browser icon:

Badge Requirements


Alpha channel only

Not supported: RGB channels. Badges use alpha channels because they must appear on both light and dark backgrounds.


72x72 or larger


png, gif, webp, ico, cur, bmp

Not supported: svg or gif animations.

Must use an HTTPS URL

Here's an example badge icon of our OneSignal logo that uses only the alpha channel.

What's Next

Learn about setting up more features, or start using the OneSignal Dashboard

Features Setup