Alerts and notifications

Last modified by Thiago Krieck on 2026/11/18 14:13

Warning
Draft

This page is a draft. The standards on it are proposals still under discussion, so they may change and should not be treated as final yet.

The standard

XWiki has three ways of telling users something, and each one has its own job. Developers should choose between them based on what the message is about and how long it stays relevant:

 Message boxTransient notificationNotifications application
Tells the user aboutThe page or what it showsSomething the user just didSomething other users did
Where it appearsInside the page contentBriefly, at the bottom of the screenIn the bell menu in the top bar
How long it staysAs long as the situation lastsA few secondsUntil the user reads it
ExampleViewing an old revision: For security reasons, the document is displayed in restricted mode as it is not the current version.Page edit form → Save: Saving... then SavedWithComments — commented by Bob Dubois

The rules below cover each of them.

  • Message boxes: A state the user should see while on the page (a warning about the page, a missing step, an error that blocks the page) should use a message box: the {{info}}, {{warning}}, {{error}} and {{success}} macros in wiki pages, #info, #warning, #error and #success in templates. Boxes should never be written by hand, so that each type always has the same icon, color and screen-reader text.
  • Type: Should match the meaning: error when something failed or is blocked, warning when something may go wrong, success when an action completed, info otherwise, since users read the color and icon before the text.
  • Transient notifications: The result of an action the user just did without leaving the page (saving, deleting, copying) should be a short notification: in progress while it runs, then replaced by done or error, so that users know the outcome without losing their place. For example, User deleted after a deletion, as in Delete confirmation.
  • Wording: Should name the action and, for errors, what failed and why, such as Deleting the user…, User deleted, Failed to save the page. Reason: …, rather than Done! or Failed://. See Action labels.
  • Announcements: Routine messages (in progress, done, info) should be announced politely (role="status"), and only errors with role="alert", so that screen readers aren't interrupted for routine updates.
  • Event notifications: Page changes, mentions and likes from other users should go through the Notifications application (the bell menu), never through message boxes or transient notifications.

Reference example: the page edit form → Save & Continue. It shows Saving..., replaces it with Saved, or with Failed to save the page. Reason: … when it fails. For message boxes, the four message macros: each box has its type icon, screen-reader text naming the type and an optional title.

alerts-reference-message-boxes.png

Message boxes: the info, warning, error and success macros

alerts-reference-saved-toast.png

Transient notification: Saved, after Save & Continue

Notes

  • Validation errors on a form field belong next to the field, not in a message box or notification. See Forms and inputs.
  • The automated checks only warn about color contrast, so boxes and notifications should be checked by hand. See Accessibility.
  • Transient notifications should be shown with XWiki.widgets.Notification rather than custom markup, so that they all look and are announced the same way.
  • The Notifications application (bell menu, notification preferences, watch button) should get its own entry.

More

Get Connected