Upgrade guides

The following lists all of the backward incompatible changes and their alternatives. If no alternative is provided, advice will be given on how to proceed.

Upgrading from 7.3.x to 7.4

AUI 7.4 updates the style of tabs, avatars, and aspects of the application header to match those found in the Atlassian Design Guidelines.
AUI 7.4 also drops support for IE 9 and IE 10; IE 11 is the oldest supported Internet Explorer version.

Internet Explorer compatibility

We no longer support Internet Explorer versions older than IE 11. The browser usage statistics from Atlassian products in Server and Cloud suggest that usage of IE 10 is between 0.03% to 0.3% of total product usage.
Dropping support for older browser versions allows AUI to take advantage of newer technologies (like flexbox, @supports in CSS, native Promises, [and more](https://caniuse.com/#compare=ie+9,ie+10,ie+11)), which in turn helps us shed some of AUI's weight in its CSS and JavaScript layers over the next several releases.

Application Header

The application header pattern includes a secondary navigation section -- these are the menu items on the right side of the navigation that contain only an icon. The design guidelines state that these secondary navigation items should not have an additional chevron icon.
To match the guidelines, you will have to change your code to include an additional .aui-dropdown2-trigger-arrowles CSS class. Check the example code:

Avatar component

The new avatar style effectively swaps the treatment of users and projects.

• User avatars are now circular.
• Project avatars are now squares with subtly rounded borders.

As part of this upgrade, if you have any custom avatar patterns, consider refactoring them to use the AUI pattern instead. If that is untenable, you will need to add the same border radius changes to your avatar components.

Tab component

The new tab style is implemented using flexbox, which allows simpler adjustment of the direction and orientation of the tabs themselves. In addition, the tab panel has been given a default top padding of 10px so that content will have reasonable separation from the tab list by default.

As part of this upgrade, you will want to check:

• If you place tab items inside another container, you may need to revise its placement in that container. The dimensions and margins of the tab group and tab items have changed slightly, which may invalidate assumptions about its visual harmony with its surroundings.
• If you are changing the orientation or placement of tabs relative to their tab panel, you will need to adjust your CSS to account for the new style. Ensure the dividing line exists between the tab items and tab panel, and that the active tab item has a line on the same side as the dividing line.

Upgrading from 7.2.x to 7.3

AUI 7.3 updates the style of flags, messages, and modal dialogs in AUI to match those found in the Atlassian Design Guidelines.

Flag and Message design

The new style for flags and messages is designed to bridge the prior ADG2 pattern and the newer ADG3 variant. It aims to balance readability of in-page messages against a less noisy flag notification. The patterns may diverge further in future.

• The pattern for flags may be revised to alter the aesthetic and their placement on the screen, though this is not a certainty.
• The design of in-page messages may be further revised to achieve better contrast with their surrounding content.

As part of this upgrade, review whether you are including buttons or links inside message text, then consider placing them in an "actions" section of the message, using the aui-nav-actions-list CSS class on an un-ordered list. See the flags, messages, or in-product help docs pages for usage examples.

Modal dialog design

The new style for modal dialogs changes the contrast between its header, footer, and content sections. Where previously the header and footer were a light grey, they are now all white, with a light grey border separating the areas. In addition, the modal now has a drop-shadow, and the colour of the blanket behind the modal has changed.

The means of achieving layout in the modal has also changed — it is now implemented with flexbox. This was done in order to properly support adding shadows to Dialog2 without changing its markup pattern.

As part of this upgrade, check that the content you add to the headers and footers of your dialogs continue to fit within them; their placement and aesthetic may need updating to work within their containers.

Upgrading from 7.1.x to 7.2

AUI 7.2 updates the style of all buttons and button-like patterns in AUI to match those found in the Atlassian Design Guidelines.

Button styles

The new button style includes a significant change to the treatment of buttons that are "pressed", such as when a dropdown is opened from a button. The colour contrast between background and text in this state has inverted; where it used to be represented with a light grey background and internal drop-shadow, it is now a dark background with light text.

The colour and contrast changes in the button pattern will necessitate revision of any custom CSS overrides you may have for button styles, such as might exist for icons inside the button. See AUI-4516 and AUI-4517 for examples.

Toolbar changes

The toolbar patterns in AUI were also updated to match the Atlassian Design Guidelines.

One notable deviation to the guidelines is found in AUI's deprecated Toolbar1 pattern: there is no whitespace between .toolbar-item elements in a .toolbar-group. The markup pattern for Toolbar1 was overly permissive, and updating this pattern to achieve the new design guidelines would both increase CSS selector count and specificity, as well as encourage continued use of the deprecated pattern.

As part of this upgrade, you should migrate any old Toolbar1-based patterns to a more appropriate markup pattern.

If you are presenting a set of actions to perform on content, such as in a rich-text editor, use the Toolbar2 pattern:

You should only use the Toolbar pattern when the semantics of your UI align with those described in the WAI-ARIA best practices for the toolbar role. In many cases, you can instead use the simpler .aui-buttons pattern:

Placement of dropdowns in markup

As part of this upgrade, also consider changing where you place the HTML for an AUI dropdown. The rounding of button corners when used in AUI's toolbar patterns rely heavily on the first and last child of the toolbar group being a button element. If the last element is something else, like a dropdown, then the right edges of a toolbar will appear sharp.
Moving all non-button HTML out of the AUI Toolbar containers will resolve this problem.

Upgrading from 7.0.x to 7.1

AUI 7.1 introduces the colours and typography from the Atlassian Design Guidelines in to a majority of AUI's components.

The new font family has a different x-height and letter spacing, and can differ between operating systems. While most line-heights and vertical spacing has been preserved, some change in the flow of content on a page is inevitable. As a result, some assumptions about available horizontal space may need to be revised.

A change of page and component colours will mean that any hard-coded hex, hsl, or rgb values in your CSS may clash with the colours that AUI now uses. If you provide a look-and-feel feature, the values provided by that feature will also clash with AUI's and will need revision.
It is recommended you use a CSS pre-processing system to declare your colour usages with variables, such that replacement of the colour values can be done in a single location.

At a technical implementation level, the new colour and typography definitions used in AUI are consumed via a shared Node package called @atlaskit/util-shared-styles. AUI consumes this package in its LESS files, whose values are substituted at build-time. A consequence of this implementation strategy is that direct consumption of AUI's source will fail, as this dependency will not be resolvable via AUI's Node package, nor through standard LESSimport behaviour.
We recognise the desire to re-use the same values that AUI uses in its CSS, and are working on a supported solution — follow AUI-4477 for more details.

Upgrading from 6.x to 7

The AUI license

The primary change between AUI 6.x and 7 is the license under which AUI is distributed.

AUI 7 is licensed under the Atlassian Developer Terms instead of Apache-2.0.

The Atlassian Developer Terms license allows third party developers to use Atlassian's SDKs to develop for the Atlassian marketplace. Applying this license to AUI means:

• If you're using AUI to build something for use within the Atlassian ecosystem, nothing changes for you. For example, if you are building a P2 plugin for a Server product, or building an Atlassian Connect app, you can continue to use AUI.
• For other usages, you may be unable to use the new version of AUI.

If you are using AUI 6.x or earlier, its Apache-2.0 license will continue to apply.

In short: if you're using AUI to build something that is *NOT* for use within the Atlassian ecosystem, you cannot use AUI 7.x, but you can continue to use AUI 6.x.

Distribution changes

AUI ships as a Node package on npmjs.com. This package includes and applies all the design assets from the Atlassian Design Guidelines to the AUI components and patterns.

Now that the ADG assets ship via the AUI Node package, and given the sunsetting of Bower, the aui-dist and aui-adg-dist repositories are also deprecated; no further distribution zip files will be published there.
The recommended approach to retrieving the flat-packed distribution files is via the dist/ folder in the Node package. Alternatively, the flat-pack zip file is pushed to Atlassian's Artifactory repository , though this method of delivery may disappear in the future.

From AUI 7 onwards, AUI is not published to its own CDN any more. For production services, it is recommended to bundle the AUI resources with your own. For prototyping and development, the contents of the Node package can be served through unpkg.com.

Upgrading from 5.8.x to 5.9

Inline dialog

Tag name

Inline dialog 1 is still deprecated but usable via the imperative AUI.InlineDialog() API. However, the Inline Dialog 2 custom element has been renamed to Inline Dialog.

persistent property / attribute

The persistent attribute is now a boolean attribute.

Events

Event listeners now do not contain the component prefix. They are only prefixed with aui-. This will be a convention for everything moving forward.

Methods removed in favour of open property / attribute

The hide(), isVisible() and show() methods have all been removed in lieu of a single open property / attribute.