Chrome Extension Notifications — Developer Guide

4 min read

Rich Notifications in Chrome Extensions

Introduction

manifest.json

{ "permissions": ["notifications"] }

Notification Types

Basic Notification

chrome.notifications.create("my-notif", {
  type: "basic",
  iconUrl: "icon128.png",
  title: "Hello!",
  message: "This is a basic notification.",
  priority: 2  // -2 to 2
});

Image Notification

chrome.notifications.create("img-notif", {
  type: "image",
  iconUrl: "icon128.png",
  title: "New Photo",
  message: "Check out this image",
  imageUrl: "preview.png"
});

List Notification

chrome.notifications.create("list-notif", {
  type: "list",
  iconUrl: "icon128.png",
  title: "Tasks Due Today",
  message: "3 tasks pending",
  items: [
    { title: "Task 1", message: "Fix login bug" },
    { title: "Task 2", message: "Update docs" },
    { title: "Task 3", message: "Deploy v2.0" }
  ]
});

Progress Notification

chrome.notifications.create("progress-notif", {
  type: "progress",
  iconUrl: "icon128.png",
  title: "Downloading...",
  message: "extension-data.zip",
  progress: 45  // 0 to 100
});

Notification Options

Event Handling

onClicked — User clicked notification body

chrome.notifications.onClicked.addListener((notificationId) => {
  chrome.tabs.create({ url: "https://example.com" });
  chrome.notifications.clear(notificationId);
});

onButtonClicked — User clicked an action button

chrome.notifications.onButtonClicked.addListener((notificationId, buttonIndex) => {
  if (buttonIndex === 0) openItem();
  else dismissItem();
});

onClosed — Notification was dismissed

chrome.notifications.onClosed.addListener((notificationId, byUser) => {
  console.log(byUser ? "User dismissed" : "System cleared");
});

Updating Notifications

chrome.notifications.update("progress-notif", {
  progress: 75,
  message: "75% complete..."
});

Clearing Notifications

chrome.notifications.clear("my-notif");
chrome.notifications.getAll((notifications) => {
  Object.keys(notifications).forEach(id => chrome.notifications.clear(id));
});

Common Patterns

Timer/Alarm Notifications

Download Progress

New Content Alerts

Message from Background to User

Best Practices

Platform Differences

Common Mistakes

Part of the Chrome Extension Guide by theluckystrike. Built at zovo.one.

← Previous mv3-migration-cheatsheet Next → omnibox-api