electron/docs/api/notification.md

Notification

Create OS desktop notifications

Process: Main

Note

If you want to show notifications from a renderer process you should use the web Notifications API

Note

On MacOS, notifications use the UNNotification API as their underlying framework. This API requires an application to be code-signed in order for notifications to appear. Unsigned binaries will emit a failed event when notifications are called.

Class: Notification

Create OS desktop notifications

Process: Main

Notification is an EventEmitter.

It creates a new Notification with native properties as set by the options.

Warning

Electron's built-in classes cannot be subclassed in user code. For more information, see the FAQ.

Static Methods

The Notification class has the following static methods:

Notification.isSupported()

Returns boolean - Whether or not desktop notifications are supported on the current system

Notification.handleActivation(callback) Windows

• callback Function
  • details ActivationArguments - Details about the notification activation.

Registers a callback to handle all notification activations. The callback is invoked whenever a notification is clicked, replied to, or has an action button pressed - regardless of whether the original Notification object is still in memory.

This method handles timing automatically:

• If an activation already occurred before calling this method, the callback is invoked immediately with those details.
• For all subsequent activations, the callback is invoked when they occur.

The callback remains registered until replaced by another call to handleActivation.

This provides a centralized way to handle notification interactions that works in all scenarios:

• Cold start (app launched from notification click)
• Notifications persisted in AC that have no in-memory representation after app re-start
• Notification object was garbage collected
• Notification object is still in memory (callback is invoked in addition to instance events)

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  // Register handler for all notification activations
  Notification.handleActivation((details) => {
    console.log('Notification activated:', details.type)
    if (details.type === 'reply') {
      console.log('User reply:', details.reply)
    } else if (details.type === 'action') {
      console.log('Action index:', details.actionIndex)
    }
  })
})

new Notification([options])

• options Object (optional)
  • title string (optional) - A title for the notification, which will be displayed at the top of the notification window when it is shown.
  • subtitle string (optional) macOS - A subtitle for the notification, which will be displayed below the title.
  • body string (optional) - The body text of the notification, which will be displayed below the title or subtitle.
  • silent boolean (optional) - Whether or not to suppress the OS notification noise when showing the notification.
  • icon (string | NativeImage) (optional) - An icon to use in the notification. If a string is passed, it must be a valid path to a local icon file.
  • hasReply boolean (optional) macOS - Whether or not to add an inline reply option to the notification.
  • timeoutType string (optional) Linux Windows - The timeout duration of the notification. Can be 'default' or 'never'.
  • replyPlaceholder string (optional) macOS - The placeholder to write in the inline reply input field.
  • sound string (optional) macOS - The name of the sound file to play when the notification is shown.
  • urgency string (optional) Linux - The urgency level of the notification. Can be 'normal', 'critical', or 'low'.
  • actions NotificationAction[] (optional) macOS - Actions to add to the notification. Please read the available actions and limitations in the NotificationAction documentation.
  • closeButtonText string (optional) macOS - A custom title for the close button of an alert. An empty string will cause the default localized text to be used.
  • toastXml string (optional) Windows - A custom description of the Notification on Windows superseding all properties above. Provides full customization of design and behavior of the notification.

Instance Events

Objects created with new Notification emit the following events:

:::info

Some events are only available on specific operating systems and are labeled as such.

:::

Event: 'show'

Returns:

• event Event

Emitted when the notification is shown to the user. Note that this event can be fired multiple times as a notification can be shown multiple times through the show() method.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.on('show', () => console.log('Notification shown!'))

  n.show()
})

Event: 'click'

Returns:

• event Event

Emitted when the notification is clicked by the user.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.on('click', () => console.log('Notification clicked!'))

  n.show()
})

Event: 'close'

Returns:

• details Event<>
  • reason Windows string (optional) - The reason the notification was closed. This can be 'userCanceled', 'applicationHidden', or 'timedOut'.

Emitted when the notification is closed by manual intervention from the user.

This event is not guaranteed to be emitted in all cases where the notification is closed.

On Windows, the close event can be emitted in one of three ways: programmatic dismissal with notification.close(), by the user closing the notification, or via system timeout. If a notification is in the Action Center after the initial close event is emitted, a call to notification.close() will remove the notification from the action center but the close event will not be emitted again.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.on('close', () => console.log('Notification closed!'))

  n.show()
})

Event: 'reply' macOS Windows

Returns:

• details Event<>
  • reply string - The string the user entered into the inline reply field.
• reply string Deprecated

Emitted when the user clicks the "Reply" button on a notification with hasReply: true.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Send a Message',
    body: 'Body Text',
    hasReply: true,
    replyPlaceholder: 'Message text...'
  })

  n.on('reply', (e, reply) => console.log(`User replied: ${reply}`))
  n.on('click', () => console.log('Notification clicked'))

  n.show()
})

Event: 'action' macOS Windows

Returns:

• details Event<>
  • actionIndex number - The index of the action that was activated.
  • selectionIndex number Windows - The index of the selected item, if one was chosen. -1 if none was chosen.
• actionIndex number Deprecated
• selectionIndex number Windows Deprecated

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const items = ['One', 'Two', 'Three']
  const n = new Notification({
    title: 'Choose an Action!',
    actions: [
      { type: 'button', text: 'Action 1' },
      { type: 'button', text: 'Action 2' },
      { type: 'selection', text: 'Apply', items }
    ]
  })

  n.on('click', () => console.log('Notification clicked'))
  n.on('action', (e) => {
    console.log(`User triggered action at index: ${e.actionIndex}`)
    if (e.selectionIndex > -1) {
      console.log(`User chose selection item '${items[e.selectionIndex]}'`)
    }
  })

  n.show()
})

Event: 'failed' Windows

Returns:

• event Event
• error string - The error encountered during execution of the show() method.

Emitted when an error is encountered while creating and showing the native notification.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Bad Action'
  })

  n.on('failed', (e, err) => {
    console.log('Notification failed: ', err)
  })

  n.show()
})

Instance Methods

Objects created with the new Notification() constructor have the following instance methods:

notification.show()

Immediately shows the notification to the user. Unlike the web notification API, instantiating a new Notification() does not immediately show it to the user. Instead, you need to call this method before the OS will display it.

If the notification has been shown before, this method will dismiss the previously shown notification and create a new one with identical properties.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.show()
})

notification.close()

Dismisses the notification.

On Windows, calling notification.close() while the notification is visible on screen will dismiss the notification and remove it from the Action Center. If notification.close() is called after the notification is no longer visible on screen, calling notification.close() will try remove it from the Action Center.

const { Notification, app } = require('electron')

app.whenReady().then(() => {
  const n = new Notification({
    title: 'Title!',
    subtitle: 'Subtitle!',
    body: 'Body!'
  })

  n.show()

  setTimeout(() => n.close(), 5000)
})

Instance Properties

notification.title

A string property representing the title of the notification.

notification.subtitle

A string property representing the subtitle of the notification.

notification.body

A string property representing the body of the notification.

notification.replyPlaceholder

A string property representing the reply placeholder of the notification.

notification.sound

A string property representing the sound of the notification.

notification.closeButtonText

A string property representing the close button text of the notification.

notification.silent

A boolean property representing whether the notification is silent.

notification.hasReply

A boolean property representing whether the notification has a reply action.

notification.urgency Linux

A string property representing the urgency level of the notification. Can be 'normal', 'critical', or 'low'.

Default is 'low' - see NotifyUrgency for more information.

notification.timeoutType Linux Windows

A string property representing the type of timeout duration for the notification. Can be 'default' or 'never'.

If timeoutType is set to 'never', the notification never expires. It stays open until closed by the calling API or the user.

notification.actions

A NotificationAction[] property representing the actions of the notification.

notification.toastXml Windows

A string property representing the custom Toast XML of the notification.

Playing Sounds

On macOS, you can specify the name of the sound you'd like to play when the notification is shown. Any of the default sounds (under System Preferences > Sound) can be used, in addition to custom sound files. Be sure that the sound file is copied under the app bundle (e.g., YourApp.app/Contents/Resources), or one of the following locations:

• ~/Library/Sounds
• /Library/Sounds
• /Network/Library/Sounds
• /System/Library/Sounds

See the NSSound docs for more information.