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