Summary

Flags 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.

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-flag
AMD Module key: N/A
Experimental API: 5.7
General API: 6

Examples

There are several flag types with different colours and icons.

Code

Flags can only be used through the Javascript API.

Javascript

Creating a flag

Note: The aui-nav-actions-list ul should be used when adding actions at the bottom of a Flag.

Closing a flag

You can close the flag by calling the close() method on the DOM element.

Flag actions

If the flag is more than just informational or there are obvious follow-up things a user could do, add a list of actions to the flag 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.

Events

When a flag is closed, the native event aui-flag-close is triggered on the flag DOM element. This event bubbles.

Options

JavaScript options

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

Option Description Possible values Default
type Sets the type of the message "success" | "info" | "warning" | "error" info
body The main content of the message. HTML none
close The closing behaviour that this flag has.
  • "auto" closing flags fade out over time, and have a close button.
  • "manual" closing flags do not fade out over time, and have a close button.
  • "never" closing flags do not fade out over time, and do not have a close button.
"auto" | "manual" | "never" "manual"
duration The time duration in milliseconds for the flag to disappear when the close option is set to "auto". number 8000
title Sets the title text of the message. Plain text none
ariaLive Sets the aria-live of the component. "off" | "polite" | "assertive" "polite"
ariaLabel Sets the aria-label of the component. string (based on type - e.g. "New information message")
ariaDescription Sets the aria-description of the component. string ""

A11Y guidelines

Side note: whether you'd follow these guidelines or not, it's always advised to at least test your markup with a screen reader software.

When the flag is set to disappear automatically, it's important to consider that some users may require more time to engage with it. Ensure the duration is long enough, or consider using the default settings, to allow sufficient interaction time for all users.

Recommendation

Please use the Web Accessibility Initiative (WAI) patterns as a reference for implementing accessible components.