Messages - AUI Documentation

Summary

Messages are the primary method for providing system feedback in the product user interface. Messages include notifications of various kinds: alerts, confirmations, notices, warnings, info and errors.

Use Banner instead of Message in page headers

Message is for use in main page content.

To make announcement at the top of the page, use Banner instead.

Work-arounds for using Message in the page header are deprecated and will be removed in AUI 11.

Status

API status:	general
Web resource key:	`com.atlassian.auiplugin:aui-message`
AMD Module key:	N/A
Experimental API:	3
General API:	5

Examples

There are several message types with different colours and icons.

Inserted with HTML

This instance was last backed up on Thursday, 18 September 2011.

Attachments will not be backed up. This needs to be done manually.

Because of incorrect data format import wasn't complete.

You have backed up your system to C:/backups/filename.xml.

System updated in the background.

Inserted with JS

Code

There are a few ways to implement messages: using HTML (or Soy to generate the HTML) or using JavaScript.

HTML

And this is just content in of the message.

This markup will make screen reader to announce message as note with type and title. User can skip it and go to further page content, or enter it to get detailed info.

It's recommended that you switch to Soy template, or even better - Web Component Message implementation. This will allow you to get all a11y labels right from a box as soon as you have id on the message.

Old (non-a11y) example

Something failed!

And this is just content in of the message.

JavaScript

Messages can be added through AUI's JavaScript API in two main ways. The most common is to inject the element inside a "context" element:

And this is just content in a Default message.

If the context selector is omitted, the message is added to a static location: an element with id="aui-message-bar".

And this is just content in a Default message.

Note that if you do not set the context, and the aui-message-bar element does not exist, the message will not appear as it has no target location.

Soy

Some details about the error so the user knows what to do.

Types of messages

When adding an HTML message, you must ensure root element (.aui-message) has the desired message class. Calling from Soy or JavaScript wraps this into one call, for convenience.

Note: icon class have been deprecated. The old message classes are also deprecated, now namespaced with aui-message-

Message type	Message class	Soy call	JavaScript function
Info	`aui-message-info`	`call aui.message.info`	`AJS.messages.info()`
Error	`aui-message-error`	`call aui.message.error`	`AJS.messages.error()`
Warning	`aui-message-warning`	`call aui.message.warning`	`AJS.messages.warning()`
Confirmation	`aui-message-confirmation`	`call aui.message.confirmation`	`AJS.messages.confirmation()`
Change	`aui-message-change`	`call aui.message.change`	`AJS.messages.change()`
Success Deprecated	`aui-message-success`	`call aui.message.success`	`AJS.messages.success()`
Generic Deprecated	`aui-message-generic`	`call aui.message.generic`	`AJS.messages.generic()`
Hint Deprecated	`aui-message-hint`	`call aui.message.hint`	`AJS.messages.hint()`

Message actions

If the message is more than just informational or there are obvious follow-up things a user could do, add a list of actions to the message body to allow the user to easily take their next step.
Actions should have the appearance of a link, but should use the appropriate HTML element for the action — for example, use a <button> when the action is handled by JavaScript or does something on the current page; use an <a> when the action can take the user to another location in the system.

Closeable

If you want to allow the user to dismiss the message

Options

HTML options

These options are set by adding classes to the root aui-message div.

Class	Effect	Example
`closeable`	Adds a Close icon to the message which closes and removes the message when clicked.
`fadeout`	Deprecated Since 5.1. Makes the message fade away after five seconds. The fadeout will be cancelled if the user interacts with it (hover or focus). Note the fadeout option is best used via JavaScript and should not be used on critical errors and other information the user must be aware of.
`aui-remove-on-hide`	Deprecated Removes the message from the DOM after being hidden

Soy options

These options are set by adding params to the Soy call.

Param	Effect	Default
content	Required. Content to display within the message.	n/a
titleContent	Title text of the message.	n/a
id	ID attribute	n/a
isCloseable	Boolean. Set to true, makes the Message closeable.	false

JavaScript options

These options are set in the options object when creating a Message with JavaScript:

Option	Description	Possible values	Default
(context argument)	You can override the default context by passing it into the first argument of the messages function. This is the only option set as an argument.	A string in the form of an ID selector	#aui-message-bar
`body`	The main content of the message.	HTML	none
`closeable`	Adds a control allowing the user to close the message, removing it from the page.	boolean	true
`id`	Gives your message an ID attribute, useful for selecting the message later.	ID string (no hash)	none
`insert`	Sets the insert point to the start (`prepend`) or end (`append`) of the context element (Option added in AUI 4.2), Since AUI 8.1.0 messages also support insertion before (`before`) and after (`after`) the context element.	prepend, append, before, after	append
`title`	Sets the title text of the message.	Plain text	none
`fadeout`	Deprecated Toggles the fade away on the message	boolean	false
`delay`	Deprecated Time to wait (in ms) before starting fadeout animation (ignored if fadeout==false)	number	5000
`duration`	Deprecated Fadeout animation duration in milliseconds (ignored if fadeout==false)	number	500
`removeOnHide`	Deprecated Makes the message element disappear from the DOM after being visually hidden	boolean	n/a

AJS.messages events

Event	Description
`messageClose`	Deprecated When a message is closed, messageClose is fired before the message is removed from the DOM, including a reference to the DOM element being removed.
`aui-message-close`	When a message is closed, aui-message-close is fired AFTER the element is removed, a reference to the message being removed is included in the event data.