JavaScript-based flash messages (Notification API)

Attention

The notification API is designed for TYPO3 backend purposes only.

The TYPO3 Core provides a JavaScript-based API called Notification to trigger flash messages that appear on the upper right corner of the TYPO3 backend. To use the notification API, load the TYPO3/CMS/Backend/Notification module and use one of its methods:

• notice()

• info()

• success()

• warning()

• error()

All methods accept the same arguments:

title

| Condition: required | Type: string |

Contains the title of the notification.

message

| Condition: optional | Type: string | Default: '' |

The actual message that describes the purpose of the notification.

duration

| Condition: optional | Type: number | Default: '5 (0 for error())' |

The amount of seconds how long a notification will stay visible. A value of 0 disables the timer.

actions

| Condition: optional | Type: array | Default: '[]' |

Contains all actions that get rendered as buttons inside the notification.

Example:

EXT:some_extension/Resources/Public/JavaScript/flash-message-demo.js

import Notification from "@typo3/backend/notification.js";

class FlashMessageDemo {
  constructor() {
    Notification.success('Success', 'This flash message was sent via JavaScript', 5);
  }
}

export default new FlashMessageDemo();

To stay compatible with both TYPO3 v11 and v12 the (deprecated) RequireJS module can still be used:

EXT:some_extension/Resources/Public/JavaScript/FlashMessageDemo.js

require(['TYPO3/CMS/Backend/Notification'], function (Notification) {
  Notification.success('Well done', 'Whatever you did, it was successful.');
});

Actions

The notification API may bind actions to a notification that execute certain tasks when invoked. Each action item is an object containing the fields label and action:

label

| Condition: required | Type: string |

The label of the action item.

action

| Condition: required | Type: ImmediateAction|DeferredAction |

An instance of either ImmediateAction (@typo3/backend/action-button/immediate-action.js) or DeferredAction (@typo3/backend/action-button/deferred-action.js).

Attention

Any action must be optional to be executed. If triggering an action is mandatory, consider using a modal instead.

Immediate action

An action of type ImmediateAction (@typo3/backend/action-button/immediate-action.js) is executed directly on click and closes the notification. This action type is suitable for e.g. linking to a backend module.

The class accepts a callback method executing very simple logic.

Example:

EXT:some_extension/Resources/Public/JavaScript/flash-message-immediate-action-demo.js

import Notification from "@typo3/backend/notification.js";
import ImmediateAction from "@typo3/backend/action-button/immediate-action.js";
import ModuleMenu from "@typo3/backend/module-menu.js";

class _flashMessageImmediateActionDemo {
  constructor() {
    const immediateActionCallback = new ImmediateAction(function () {
      ModuleMenu.showModule('web_layout');
    });

    Notification.info('Nearly there', 'You may head to the Page module to see what we did for you', 10, [
      {
        label: 'Go to module',
        action: immediateActionCallback
      }
    ]);
  }
}

export default new _flashMessageImmediateActionDemo();

To stay compatible with both TYPO3 v11 and v12 the (deprecated) RequireJS module can still be used:

EXT:some_extension/Resources/Public/JavaScript/FlashMessageImmediateActionDemo.js

require(['TYPO3/CMS/Backend/Notification', 'TYPO3/CMS/Backend/ActionButton/ImmediateAction'], function (Notification, ImmediateAction) {
  const immediateActionCallback = new ImmediateAction(function () {
    require(['TYPO3/CMS/Backend/ModuleMenu'], function (ModuleMenu) {
      ModuleMenu.showModule('web_layout');
    });
  });

  Notification.info('Nearly there', 'You may head to the Page module to see what we did for you', 10, [
    {
      label: 'Go to module',
      action: immediateActionCallback
    }
  ]);
});

Deferred action

An action of type DeferredAction (@typo3/backend/action-button/deferred-action.js) is recommended when a long-lasting task is executed, e.g. an Ajax request.

This class accepts a callback method which must return a Promise (read more at developer.mozilla.org).

The DeferredAction replaces the action button with a spinner icon to indicate a task will take some time. It is still possible to dismiss the notification, which will not stop the execution.

Example:

EXT:some_extension/Resources/Public/JavaScript/flash-message-deferred-action-demo.js

import Notification from "@typo3/backend/notification.js";
import DeferredAction from "@typo3/backend/action-button/deferred-action.js";
import $ from 'jquery';

class _flashMessageDeferredActionDemo {
  constructor() {
    const deferredActionCallback = new DeferredAction(function () {
      return Promise.resolve($.ajax(/* Ajax configuration */));
    });

    Notification.warning('Goblins ahead', 'It may become dangerous at this point.', 10, [
      {
        label: 'Delete the internet',
        action: deferredActionCallback
      }
    ]);
  }
}

export default new _flashMessageDeferredActionDemo();

To stay compatible with both TYPO3 v11 and v12 the (deprecated) RequireJS module can still be used:

EXT:some_extension/Resources/Public/JavaScript/FlashMessageDeferredActionDemo.js

require(['jquery', 'TYPO3/CMS/Backend/Notification', 'TYPO3/CMS/Backend/ActionButton/DeferredAction'], function ($, Notification, DeferredAction) {
  const deferredActionCallback = new DeferredAction(function () {
    return Promise.resolve($.ajax(/* Ajax configuration */));
  });

  Notification.warning('Goblins ahead', 'It may become dangerous at this point.', 10, [
    {
      label: 'Delete the internet',
      action: deferredActionCallback
    }
  ]);
});