Notification

Preview

When to use

Use a notification to communicate status, feedback, or important information that is directly related to the current context. It works well for:

• Confirming that an action succeeded (e.g., "Your changes have been saved").
• Alerting the user to a problem with their input or a system error.
• Warning about a condition that needs attention before the user continues.
• Providing neutral, contextual information relevant to the page or form.

When not to use

• Don't use a notification for information that requires an immediate decision from the user — use a Dialog instead.
• Avoid using it for content that is not related to a user action or system state.
• Don't use it to replace form validation errors on individual fields — use inline field-level error messages for that.

Behaviour

Notifications are inline — they appear within the page layout and persist until the condition they describe is resolved or the user takes action. They do not auto-dismiss.

When a notification includes a slot for actions, those actions (typically a link or a small button) are secondary to the message itself. The message should make sense without the action.

Anatomy

• Icon — a small icon reinforcing the notification type (Critical, Warning, Success, or Neutral). Always present.
• Header (optional) — a short, bold title that summarises the message. Use when the notification needs a clear label separate from the body.
• Body — the main message text. Concise and actionable.
• Slot (optional) — an area for an action, such as a link or secondary call to action.

Variants

Type — determines the visual appearance and semantic meaning:

• Critical — use for errors or failures that block the user from proceeding (e.g., a form submission error, a failed payment).
• Warning — use for conditions that may cause problems but don't block progress (e.g., incomplete information, an upcoming expiry).
• Success — use to confirm that an action was completed successfully.
• Neutral — use for informational messages that don't carry an urgency or outcome.

Header

• With header — includes a title above the body text. Use when the type alone isn't enough context.
• Without header — body-only. Use for short, self-explanatory messages.

Centered text

• Left-aligned — the default. Use in most contexts.
• Centered — use when the notification appears in a centred or narrow layout context.

Slot

• Without slot — message only.
• With slot — includes space for an action (a link or inline button) below the body text.

States

Notifications are static once rendered. The type variant conveys the current state:

• Critical — error or failure state.
• Warning — caution or at-risk state.
• Success — completed or confirmed state.
• Neutral — informational, no urgency.

Placement & layout

Place notifications close to the content they relate to. An error in a form section should appear at the top of that section, not at the top of the page.

Notifications span the full width of their container. Don't constrain them to a narrow column if the surrounding content uses a wider layout.

Keep the message short. If the notification body requires more than two to three sentences, consider whether a different pattern (e.g., a summary section or help text) is more appropriate.

Accessibility

• Notifications must be announced to screen readers. Use role="status" for Success and Neutral notifications (polite); use role="alert" for Critical and Warning notifications (assertive).
• Don't rely solely on colour to convey meaning — the icon and message text must also communicate the type.
• If the notification appears dynamically after a user action, ensure it is inserted into a live region so assistive technologies announce it.
• Action links within the slot must have descriptive labels.

Related components

• Dialog — when the message requires an immediate decision or acknowledgement before proceeding.
• Tag — for compact status labels that sit inline with content rather than as a standalone message.
• Input — for field-level validation errors rather than page- or section-level notifications.