Alerts and notifications
Last modified by Thiago Krieck on 2026/11/18 14:13
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 box | Transient notification | Notifications application | |
|---|---|---|---|
| Tells the user about | The page or what it shows | Something the user just did | Something other users did |
| Where it appears | Inside the page content | Briefly, at the bottom of the screen | In the bell menu in the top bar |
| How long it stays | As long as the situation lasts | A few seconds | Until the user reads it |
| Example | Viewing 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 Saved | WithComments — 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.

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

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.