Notification Balloons

Sometimes, it is required to show relevant information without interrupting the developer’s flow. The most general way is to use notification balloons. They inform users of the events or system states related to a project or IDE.

To display a notification, provide two things. First, a notification group to act as a configurable channel. Then, a notification instance itself.

Notification Group

Declare a notification group as an extension in the plugin descriptor. It is registered using the com.intellij.notificationGroup extension point. Set the display type to BALLOON constant. Then, provide a human-readable identifier.

<extensions defaultExtensionNs="com.intellij">
   <notificationGroup id="Bagel" displayType="BALLOON" />
</extensions>

Timeline notification

Next, create a new Notification instance. The constructor takes three arguments:

Notification group ID
Content text
Type (controls the icon that's displayed)

Use the notify method and pass in the current project to show the notification in its associated frame.

Notification("Bagel", "Bagel was eaten", NotificationType.INFORMATION)
   .notify(e.project)

By default, a notification is timed, as it will automatically disappear after 10 seconds. However, it will remain in the Notifications tool window, until cleared, in the Timeline section.

Configuring Notifications

Notifications are configured in Settings | Appearance & Behavior | Notifications. Observe the Bagel notification group with Popup type set to Balloon and Show in tool window being checked.

See Notifications Product Help for specific user-facing options.

Notification Icons

Customize the notification icon according to message severity. Use the constants from NotificationType.

Generic information: INFORMATION.
Disruptions or events requiring user action: WARNING.
Critical events or states: ERROR.

When possible, use a plugin or functionality icon instead of the Information icon. See the Icons section for more information.

Notification Actions

A notification balloon can contain actions, rendered as a link or button.

Notification("Bagel", "Bagel was eaten", NotificationType.INFORMATION)
  .addAction(NotificationAction.createSimpleExpiring("Track calories") {
    // add an action
  })
  .notify(e.project)

Chain addAction method with createSimpleExpiring method, which provides a trailing lambda for the action handler. When the user clicks it, the notification dismisses automatically. However, it will stay in the Notification tool window with the hyperlink greyed-out.

Multiple Actions

Anything beyond two actions gets hidden in a More menu. Put the most important actions first.

Notification Title and Body

To give more context, use a title and a body. The title briefly describes what happened, and the body explains the impact or what the user can do about it. The overloaded constructor takes an extra string before the content – that’s the title.

Notification("Bagel", "Bagel was eaten", getBagelCounterMessage(), NotificationType.INFORMATION)
  .notify(e.project)

Suggestions

In some cases, the functionality needs to prompt or notify the user to take action or provide input.

Suggestions show the primary action as a noticeable button. Unlike timed notifications, suggestions won’t go away on their own. The user has to act and dismiss them explicitly. Their notification group is configured as STICKY_BALLOON.

<notificationGroup id="Bagel File"
                   displayType="STICKY_BALLOON" />

To mark the notification as a suggestion, set its suggestion type to true.

Notification("Bagel File", "Bagel file detected", NotificationType.INFORMATION)
  .setSuggestionType(true)
  // ...

Suggestions have a dedicated section in the Notifications tool window.

Tool Window Notifications

A tool window can trigger a long-running operation. For example, the Find in Files action takes a couple of seconds to search for a string in a large project tree, doing that in the background. When there are no matches, a notification balloon is shown. However, instead of the usual location, the notification balloon is displayed directly next to the tool window icon. In the plugin descriptor, declare the notification group with a display type set to TOOL_WINDOW. As the notification group’s notifications are explicitly bound to a specific tool window, provide its identifier in the toolWindowId attribute.

<notificationGroup
  id="Order in Bakery"
  displayType="TOOL_WINDOW"
  toolWindowId="Bakery"
/>

<toolWindow
  id="Bakery"
  ...
/>

The toolWindowId matches the id value declared in the com.intellij.toolWindow extension.

In the code, use the standard Notification.notify method to show it.

Notification("Order in Bakery", "Bagel is ready", NotificationType.INFORMATION)
  .addAction(NotificationAction.createSimpleExpiring("Eat bagel") {
      // handle 'Eat bagel' link
   })
notification.notify(e.project)

Such notification is automatically dismissed on any keypress or mouse click. Due to space constraints, the notification title should be as short as possible. Additionally, use at most one notification action, which will be rendered as a hyperlink. Generally, the tool window notifications don’t need to be shown in the Notifications tool window. See the corresponding section for the implementation.

Icons

The UI guidelines recommend using a plugin or functionality icon instead of the generic Information icon. Provide an icon along with its accompanying constant. The Notification.setIcon overrides the icon from the constructor argument.

Notification("Bagel", "Bagel was eaten", NotificationType.INFORMATION)
  .setIcon(Icons.Bagel)
  //...

Localization

The notification group identifier is not a technical identifier, but a human-readable string directly mapped to the IDE settings user interface. However, it can be localized.

Make sure that the plugin descriptor declares a plugin resource bundle:

<resource-bundle>messages.BagelBundle</resource-bundle>

Then declare a key element that contains a localized notification group ID.

<notificationGroup id="Bagel File"
  key="bagel.file.notification.group"
  displayType="STICKY_BALLOON" />

Configuring notification display settings

Some use-cases require a specific display configuration for the notification balloons. Use them carefully, as they might go against the default user experience guidelines.

Notification balloons without entries in the Notifications tool window

Occasionally, there are notifications that do not need to be logged in the Notification tool window. This is the standard case with Tool Window notifications. However, there are other usages as well. A Hotswap Reload action or a Breakpoint Hit is shown as notification balloons and then completely hidden. Such a notification group has the isLogByDefault attribute set to false. This matches the Show in tool window option being disabled.

Notifications tool window entry without a notification balloon

To log a new entry into the Notifications tool entry without showing a balloon, configure the displayType to NONE. This matches the Popup type list being set to No popup.

Obsolete API

Previously, there were multiple SDK approaches to notification balloons. They are considered to be obsolete or too complex.

NotificationGroup is considered an internal data structure. Its factory methods are replaced with Notification constructor and subsequent builder methods. The NotificationGroupManager, its getNotificationGroup method are no longer necessary, as the reference to the notification group is resolved via the notification group identifier.
The Notifications.Bus.notify method can be replaced with the notify method on the Notification instance.
NotificationsManager is considered to be internal. Its methods should be replaced by the corresponding methods in the Notification class.

Summary

A notification group is a user-configurable channel for notifications. Directly maps to a configuration item in the IDE settings.
Timeline notification shows for 10 seconds and is automatically dismissed. The primary action is shown as a hyperlink. Uses a BALLOON constant in the notification group.
Suggestion needs to be dismissed explicitly. The primary action is shown as a button. Uses a STICKY_BALLON constant in the notification group. Needs to set setNotificationType(true) on the Notification instance. Suggestions are shown in a dedicated section in the Notifications tool window.
Tool Window Notification visually points to the specific tool windows. The primary action is shown as a hyperlink. It is automatically dismissed on click or keypress.
Use the Notification class to create instances, its builder methods to configure, and the notify method to show a notification.

23 March 2026