Chrome Extension Notifications API: Complete Guide to Desktop Alerts (2026)

Why Use Chrome Extension Notifications?

Chrome’s chrome.notifications API lets your extension display rich system-level notifications — even when the popup is closed and the user is focused on another app. They’re essential for time-sensitive alerts, background task completions, and user re-engagement.

Unlike web notifications, extension notifications support multiple templates, action buttons, and progress indicators out of the box.

Setting Up Notifications

Add the notifications permission to your manifest:

{
  "manifest_version": 3,
  "name": "Notification Demo",
  "version": "1.0",
  "permissions": ["notifications"],
  "background": {
    "service_worker": "service-worker.js"
  }
}

Four Notification Templates

1. Basic Notification

The most common type — a title, message, and icon:

chrome.notifications.create('basic-example', {
  type: 'basic',
  iconUrl: chrome.runtime.getURL('icons/icon-128.png'),
  title: 'Download Complete',
  message: 'report-Q4-2026.pdf has been saved to Downloads.',
  contextMessage: '2.4 MB • 3 seconds',
  priority: 1
});

2. Image Notification

Includes a large image preview — great for screenshot tools or media extensions:

chrome.notifications.create('image-example', {
  type: 'image',
  iconUrl: chrome.runtime.getURL('icons/icon-128.png'),
  title: 'Screenshot Captured',
  message: 'Click to view or share your screenshot.',
  imageUrl: capturedImageDataUrl
});

Platform note: Image notifications do not display on macOS. The system falls back to a basic notification.

3. List Notification

Displays multiple items — ideal for email summaries or task updates:

chrome.notifications.create('list-example', {
  type: 'list',
  iconUrl: chrome.runtime.getURL('icons/icon-128.png'),
  title: '3 New Messages',
  message: 'You have unread messages',
  items: [
    { title: 'Alice', message: 'Hey, are you available for a call?' },
    { title: 'Bob', message: 'PR #42 has been approved' },
    { title: 'Carol', message: 'Meeting moved to 3 PM' }
  ]
});

Platform note: macOS only displays the first item.

4. Progress Notification

Shows a progress bar — perfect for uploads, downloads, or long-running tasks:

let progress = 0;

chrome.notifications.create('progress-example', {
  type: 'progress',
  iconUrl: chrome.runtime.getURL('icons/icon-128.png'),
  title: 'Uploading backup...',
  message: 'Please wait',
  progress: 0
});

const interval = setInterval(() => {
  progress += 10;
  chrome.notifications.update('progress-example', { progress });

  if (progress >= 100) {
    clearInterval(interval);
    chrome.notifications.update('progress-example', {
      title: 'Upload Complete',
      message: 'Your backup has been saved.',
      progress: 100
    });
  }
}, 500);

Platform note: macOS shows a percentage text instead of a visual progress bar.

Template Comparison

Feature	Basic	Image	List	Progress
Title & message	✅	✅	✅	✅
Icon	✅	✅	✅	✅
Large image	❌	✅	❌	❌
Multiple items	❌	❌	✅	❌
Progress bar	❌	❌	❌	✅
Action buttons	✅	✅	✅	✅
macOS full support	✅	❌	Partial	Partial

Action Buttons

Add up to two action buttons to any notification:

chrome.notifications.create('action-example', {
  type: 'basic',
  iconUrl: chrome.runtime.getURL('icons/icon-128.png'),
  title: 'New Extension Update Available',
  message: 'Version 2.1 includes performance improvements.',
  buttons: [
    { title: 'Update Now' },
    { title: 'Remind Later' }
  ]
});

Event Handling

Handle all notification interactions in your service worker:

// User clicked the notification body
chrome.notifications.onClicked.addListener((notificationId) => {
  if (notificationId === 'action-example') {
    chrome.tabs.create({ url: 'https://extensionbooster.com' });
    chrome.notifications.clear(notificationId);
  }
});

// User clicked an action button
chrome.notifications.onButtonClicked.addListener((notificationId, buttonIndex) => {
  if (notificationId === 'action-example') {
    if (buttonIndex === 0) {
      chrome.runtime.requestUpdateCheck(() => {});
    } else {
      // Schedule reminder via chrome.alarms
      chrome.alarms.create('update-reminder', { delayInMinutes: 60 });
    }
    chrome.notifications.clear(notificationId);
  }
});

// Notification was dismissed
chrome.notifications.onClosed.addListener((notificationId, byUser) => {
  if (byUser) {
    console.log(`User dismissed ${notificationId}`);
  }
});

Priority Levels

Priority	Behavior
`-2` to `-1`	ChromeOS notification center only (no popup)
`0`	Default behavior
`1`	Higher priority, shown more prominently
`2`	Highest priority, requires user interaction

Best Practices

Don’t spam — Rate-limit notifications. Chrome may throttle extensions that send too many.
Be informative — Every notification should provide actionable information.
Clear completed notifications — Remove progress notifications when the task finishes.
Use unique IDs — Reuse notification IDs to update existing notifications rather than creating duplicates.
Test cross-platform — macOS uses native notifications with different rendering. Always verify.
Place listeners in service workers — Notifications fire even when the popup isn’t open.

What’s Next

Notifications keep users engaged with your extension even when they’re not actively using it. Start with basic notifications, add action buttons for interactivity, and always respect the user’s attention.

Track how your notification strategy impacts user retention with ExtensionBooster’s analytics tools.