Skip to content

notifications.md

Latest commit

 

History

History
169 lines (114 loc) · 5.09 KB

notifications.md

File metadata and controls

169 lines (114 loc) · 5.09 KB
Raw

notifications

Documentation: Chrome Notifications API

A promise-based wrapper for the Chrome notifications API to create and manage desktop notifications.

Methods

Events

Listeners subscribe directly to the native event. If the notifications API or the requested event is unavailable, subscription throws; it does not log a warning or return an empty unsubscribe function. Call isAvailableNotifications() explicitly when you need to check whether the namespace is available in an extension context. It does not check individual events.

clearNotification

clearNotification(notificationId: string): Promise<boolean>

Clears the notification with the specified ID, resolving to true if the notification existed and was cleared.

createNotification

createNotification(
  options: chrome.notifications.NotificationOptions,
  notificationId?: string
): Promise<string>

Creates a notification with the given options and optional ID, returning the notification ID.

getAllNotifications

getAllNotifications(): Promise<object>

Retrieves all currently displayed notifications. The returned object maps notification IDs to true values, as provided by chrome.notifications.getAll.

getNotificationPermissionLevel

getNotificationPermissionLevel(): Promise<string>

Gets the current permission level for notifications (e.g., "granted" or "denied").

updateNotification

updateNotification(
  options: chrome.notifications.NotificationOptions,
  notificationId: string
): Promise<boolean>

Updates an existing notification with new options, resolving to true if the notification was updated.

isAvailableNotifications

isAvailableNotifications(method?: ApiMethodName<typeof chrome.notifications>): boolean

The optional method is a native function name, for example isAvailableNotifications("create"). Import the public ApiMethodName type from @addon-core/browser for your own typed helpers. This checks callable presence without invoking the method; permissions and argument support still require handling.

Returns true when the notifications namespace is present on the API selected by browser() in the current context. Returns false if the namespace or WebExtension environment is absent, or if accessing it throws. The check is synchronous, does not log, and reads the current API on every call without caching. Without an argument, it checks namespace presence only. Pass a native method name to also check that it is callable. Neither form verifies permissions, argument support, or a successful operation. See method availability.

import {isAvailableNotifications} from "@addon-core/browser";

if (isAvailableNotifications()) {
    // The namespace is present; handle operation-specific failures when using it.
}

clearAllNotifications

clearAllNotifications(): Promise<void>

Clears all currently displayed notifications.

onNotificationsButtonClicked

onNotificationsButtonClicked(
  callback: (notificationId: string, buttonIndex: number) => void
): () => void

Adds a listener for when a button on a notification is clicked. Returns an unsubscribe function.

onNotificationsClicked

onNotificationsClicked(
  callback: (notificationId: string) => void
): () => void

Adds a listener for when a notification itself is clicked. Returns an unsubscribe function.

onNotificationsClosed

onNotificationsClosed(
  callback: (notificationId: string, byUser: boolean) => void
): () => void

Adds a listener for when a notification is closed, including whether it was closed by the user. Returns an unsubscribe function.

onNotificationsPermissionLevelChanged

onNotificationsPermissionLevelChanged(
  callback: (level: chrome.notifications.PermissionLevel) => void
): () => void

Adds a listener for changes to the notifications permission level. Returns an unsubscribe function.