Table of Contents Previous entry (api:GM_log) Next entry (api:GM_openInTab)

GM_notification(details, ondone), GM_notification(text, title, image, onclick)

GM_notification allows users to display notifications on the screen, using a provided message and other optional parameters.

The function takes several parameters. Either a details object or multiple parameters.

The details object can have the following attributes, from which some can also be used as direct parameter.

The available options include:

• text: A string containing the message to display in the notification.
• title: The title of the notification.
• tag: ^v5.0+ This tag will be used to identify this notification. This way you can update existing notifications by calling GM_notification again and using the same tag. If you don't provide a tag, a new notification will be created every time.
• image: The URL of an image to display in the notification.
• highlight: A boolean flag whether to highlight the tab that sends the notfication (required unless text is set)
• silent: A boolean flag whether to not play a sound
• timeout: The time, in milliseconds, after which the notification should automatically close.
• url: ^v5.0+ A URL to load when the user clicks on the notification. You can prevent loading the URL by calling event.preventDefault() in the onclick event handler.
• onclick: A callback function that will be called when the user clicks on the notification.
• ondone A callback function that will be called when the notification is closed (no matter if this was triggered by a timeout or a click) or the tab was highlighted

The function does not return a value.

If no url and no tag is provided the notification will closed when the userscript unloads ^v5.0+(e.g. when the page is reloaded or the tab is closed).

Here is an example of how the function might be used:

GM_notification({
  text: "This is the notification message.",
  title: "Notification Title",
  url: 'https:/example.com/',
  onclick: (event) => {
    // The userscript is still running, so don't open example.com
    event.preventDefault();
    // Display an alert message instead
    alert('I was clicked!')
  }
});

const clicked = await GM.notification({ text: "Click me." });