AUI 9 upgrade guides
Upgrading from 8.x to 9.0
AUI ships focus styles that target default HTML element appearance when focussed. Previously, AUI set a style for the :focus pseudo-selector. AUI 9 also sets a style for the :focus-visible pseudo-selector.
There is one behavioural difference between :focus and :focus-visible.
- When an element is styled using :focus, a focus ring will be drawn whenever the element receives browser focus, regardless of how it was focussed — by mouse click, by keyboard input, or by programmatic means.
- When an element is styled using :focus-visible, a focus ring will only be drawn when the browser determines that focus should be made visually apparent. Typically, this means a focus ring will not be shown when focussed by mouse click, but will be shown when focussed by keyboard.
This update to using :focus-visible has been made to support the AUI 9 accessibility changes. Many AUI components now have an explicit focus indicator — dropdowns, dialogs, and more. If elements are only styled with :focus, a focus ring would be drawn when mouse users interact with elements, which they may find jarring. By adding :focus-visible, mouse users will not see focus rings after clicking elements, but other users will.
Not every browser supports :focus-visible. As a consequence, when upgrading, you may see focus rings on elements you did not expect. To account for this, AUI also supports the WICG focus-visible polyfill. If you add this polyfill to your application, focus rings should only be visible in non-mouse-usage scenarios.
Please check the browser support matrix for :focus-visible and decide whether you want to ship the WICG focus-visible polyfill, or whether the standard :focus behaviour will be acceptable in your application.
It will be focused as the first thing after dialog being opened unless
you set explicitly the
Make sure the close button:
- is a button (and has a
type="button"just in case you put it within HTML form somehow)
- has an aria-label attribute, with a translation string that evaluates to "Close"
- is in tab order (it will be by default if it's a button)
Inline Dialog 2
Inline dialog element is now focused after opening.
Make sure you set
aui-inline-dialog element to give screen reader friendly
description of the the dialog's content.
When aria-label is missing the AT will read whole content of the dialog.
Layered elements except Dialog2 will not alter their allocation in DOM tree by default.
To maintain a natural tab order for keyboard users, layered elements should be rendered as the next sibling of their trigger.
It may happen that due to the design of your application the layered components may get obscured - i.e. being clipped
by the parent container with
overflow:hidden; CSS property set.
You may need to alter your application's CSS to adjust to the new behaviour.
In rare cases when such adjustments are not possible - you may specify a rendering DOM container for any layered component.
Upon displaying of such layered component - it will temporarily move it's subtree into the specified container - allowing for unobstructed rendering.
You should always choose the closest container allowing for unobstructed render.
You are responsible for ensuring the component is properly cleaned up, adequately to your application's lifecycle.
In order to specify a rendering DOM container, set the
to a selector matching the container element:
data-aui-dom-containerattribute is set but the selector matches multiple elements - it will default to first available match.
data-aui-dom-containerattribute is set but the selector does not match to any existing elements it will default to
data-aui-dom-containerattribute is not set, the dropdown will be left in place.
Even though this API is available for all layered components, only the components that guarantee adequate tab, keyboard and/or focus flow management will expose this API in their documentation.
Always refer to the component's documentation to see if it exposes any means to overcome similar rendering obstacles, i.e. by setting proper alignment.
Previously, specific ARIA attributes would receive styling when used in a dropdown container. Now, ARIA attributes receive no explicit styling.
If you are using the markup-based pattern (not the web-component pattern) for your dropdowns, You must use one the following patterns to receive the dropdown item aesthetic:
- Use an <a> HTML element if the dropdown item will take the user to another page.
- Use a <button> HTML element if the dropdown item will do something dynamic.
- Use the .aui-dropdown2-radio or .aui-dropdown2-checkbox CSS classes to make an item present as a radio or checkbox respectively.
Note that these are changes to the CSS and affect visual aesthetic. You are responsible for using valid, semantic markup so that the items are perceived correctly in non-visual contexts, such as screen readers.
Previously, the application header's logo was wrapped in a <h1> element. The <h1> element should only be used inside the page's main content. The logo element has now been replaced with a <span> element.
The pattern's <nav> element must have an aria-label with a translated value of "site". This allows screen reader users to perceive the application header as "site navigation".
Make sure that the logo link has translation string that interpolates to "Go to home page" label.
|Old markup||New markup|
Page layout changes
The .aui-panel class is gone
AUI used to include an .aui-panel CSS class. Its purpose was wholly replaced by .aui-page-panel in AUI 5. The upgrade is a simple 1:1 mapping: find and replace all .aui-panel with .aui-page-panel.
Page structure changes
The page layout pattern was updated; some markup changes were made to allow easier placement of key landmark roles, as well as to provide recommended labeling for each. Of note in the changes are:
- Where to place the <main> element on your page.
- The position of the sidebar has changed in markup.
- The recommended tag names of interstitial markup between page structure and content are slightly updated.
- Removal of redundant role attributes where all supported browsers and screen readers understand the native semantic of recommended tags.
Here are how some typical page layouts have changed in markup:
Please read the full page layout documentation page for more details on these changes.
Soy template changes
Previously, the aui.page.pagePanelContent template output a <section> element and had no id value.
In AUI 9, this template now outputs a <main> element with a default id value of main. It will also output the appropriate role attribute.
Changes to hiding and showing elements
AUI used to use
aria-hidden attribute to visually hide elements, which is an incorrect usage of this attribute.
To improve how elements are shown and hidden, we made the following changes:
- We removed invalid uses of
aria-hiddenand replaced some of them with
- For several elements, we now use the
openattribute to indicate whether the element should be visible or not.
- AUI's CSS reset sets
display:none !importanton any element with the hidden attribute.
If your code tests for the visibility of an element, check for the presence of the
attribute and the absence of a
If an element should be hidden immediately, add the
hidden attribute to it.
If you animate any elements when they appear or disappear, you should do this with the
hidden attribute takes precedence over
open and will take effect
immediately; it will not be possible to animate visibility when this attribute is added to an element.
Previously in our docs examples markup for Dialog2 included
aria-hidden="true" attribute on
Now you should add
|Old markup||New markup|
If you are still constructing dropdowns using markup instead of webcomponent you may need to update your HTML. If you are using Soy templates provided by AUI you are fine if not, make changes described below.
|Old markup||New markup|
Refactoring aria-hidden attributes required also changes in Layer component.
|Old behaviour||New behaviour|
AUI library changes
Sidebar expand button
We replaced custom icon with icon font. Make sure that the span now has
|Old markup||New markup|
"Message" close icon was removed. Following classes are no longer supported:
- .aui-message .icon-close
- .aui-message .icon-close-inverted
- .aui-message.error .icon-close
jQuery ajaxSettings configuration was removed. Please specify it globaly for product or add it per request where needed. More information here https://api.jquery.com/jQuery.param/
In previous versions AUI relied on the
dateFormat option from the jQuery UI datepicker widget. It was used as a placeholder for the input of type "date" if the "overrideBrowserDefault" option was set to "true".
Since the default format is represented by string "yy-mm-dd" it was confusing users because "yy" stands for the long year format (4-digits) - not the short, 2-digits year format.
We decided to break the dependency between the input placeholder and the format string by extending the configuration API and allowing the placeholder to be set explicitly. That requires you to review all the usages of the datepicker widget and set placeholders where they are needed to clarify understanding of given input purpose.
Our recommendation here is to not use placeholders and put the expected date format next to the input label - mostly for the accessibility reasons. Use placeholders only as a last resport. We suggest representing real values - not the format string:
eg. 2020-01-29 instead of
Upgrading from 9.0.x to 9.1
AUI library changes
AUI's version of
Popper.js - a third party library supporting AUI's layered components - has been bumped to v2.4.4, up from v1.14.5.
Due to changes introduced with
Popper.js - shape of certain attributes might have changed for those components.
x-* have been replaced with
For details - visit Popper.js Migration guide
|Old markup||New markup|
Even though these attributes have been used as internal API only and not explicitly guaranteed - for compatibility
x-placement attribute is provided by AUI layered components.
Its use is considered as DEPRECATED, meaning - the attribute will be removed with further versions of AUI. If your application depends on the provided data - please adapt to new, namespaced markup
Upgrading from 9.2.x to 9.3.0
AUI's tooltips have been re-implemented using popper.js, the same library AUI uses for its other layered elements such as inline dialog, dropdown, modal, etc. As a result, tooltips are positioned correctly in more scenarios, and the bundle size for AUI is reduced.
Some behaviours have been hard-coded to match the ADG recommendations, eg. delay for tooltip appearance, removal of animation, removal of arrows pointing from tooltip to its trigger.
Previously, AUI used the jQuery Tipsy plugin to render tooltips. This was considered an internal implementation
detail of AUI and was not intended to be used outside of AUI. As of AUI 9.3.0, calling
AJS.$(selector).tipsy() will not work.
If you are using tooltips, you should consume the AUI tooltip component
directly and use the
If you still require the jQuery Tipsy extension, you have two options:
- Using Node: add the @atlassian/tipsy NPM dependency to your project and depend on this library directly.
- Using the Atlassian Plugin: add a web-resource dependency for com.atlassian.auiplugin:jquery-tipsy to your feature. Note that this web-resource is deprecated and will be removed in a future major version.
The new implementation of tooltips relies on single DOM node inserted at the bottom of document. Its text content changes every time new tooltip shows up. This was done mostly because removal of tooltip animations makes it impossible to have more than one tooltip visible in the same time on screen. It also slightly improves the DOM mutation performance.
Focus style changes
AUI ships focus styles that target default HTML element appearance when focussed. These styles were previously been shipped as part of AUI's CSS reset. In AUI 9.3, the focus styles are now opt-in. They have been extracted in to their own CSS file and dedicated web-resource. They have also been hidden behind a CSS feature flag.
As a consequence, some elements like hyperlinks (<a>) will no longer receive a focus ring style consistent with AUI's other components.
If you want to apply AUI's focus styles to default HTML elements, refer to the browser focus documentation page for usage instructions.
Upgrading from 9.5.x to 9.6.0
Inline Dialog 2 accessibility attributes changes
Why we change?
The current implementation of the Inline Dialog 2 misleads the Screen Reader's users. It happens because the Inline
Dialog's 2 trigger by default gets
attributes, and the popup element gets
As a result when a user moves focus on the trigger the Screen Reader announces that he/she is on the popup menu's trigger which is collapsed right now, but on pressing the trigger users redirected to a dialog, what is not expected by user.
In order to make the Inline Dialog 2 more accessible and fix inconsistencies we made the following changes:
Removed default attribute
Now there is no any role on a popup element of the Inline Dialog 2 by default. It means that if the popup element is focused the Screen Reader will announce it as a group (not as a dialog as it was).
Added inner handlers for cases when the
role='dialog'attribute is provided manually by developers.
So if you add
aria-expandedwill not be added to the trigger element.
How to upgrade
The only what you need is to review all entrances of the Inline Dialog 2 component in codebase and
decide on each case if the case should be considered as a popup menu/custom component/extended tooltip
or a non-modal dialog.
In case it is a:
- Popup menu / custom component / extended tooltip. No changes is needed.
- Non-modal dialog. You need to add
A distinction between informative and decorative icons has been clarified further, and the approach to informative icons (in other words, cases where the icon stands alone in a control) was changed.
If you're using an informative icon from soy, no change is required.
However, if an icon is defined in HTML like this:
then you should consider replacing it with the new form:
Both forms are supported, but the new one is preferred.
Upgrading to 9.7.0
Replace Multi-select with Select2
The default browser behavior of the select element requires to use
modifier keys (Ctrl or Cmd) with the mouse or Up, Down, or Space keys in
order to select multiple items. This behavior is non-intuitive and not
accessible. Therefore, in this version we deprecate the
multi-select component and ask you to migrate its uses to
multi-select and initialize
|Old code||New code|