AUI 10 upgrade guides - AUI Documentation

Upgrading from 9.x to 10.0

Deprecated components & patterns removal

From AUI 10, some deprecated components are removed.

Dropdown 1

Toolbar 1

checkbox-multiselect

This was an experimental, undocumented component. There were no usages of it within Atlassian code and no usages were detected in Marketplace plugins.

It was built on Dropdown2 and updated the label with the selected options.

AJS.Template

AJS.Template was a templating engine shipped with AUI. It should be replaced with either Soy JS templates or the I18n system as appropriate.

It will remain available as a deprecated package on NPM, but we do not recommend using it.

Old dark mode

The first version of dark mode has been removed. It conflated color mode (light or dark) with theme (could be e.g. high-contrast). It has been replaced with a new dark theme and color mode based on the same design tokens as Atlaskit. This new system is what all the Data Center products use now. Learn how to prepare your Data Center app for dark theme

Soy templates

From AUI 10.0.0 some of the soy templates are no longer available.

Please search your codebase for references of removed templates (listed below).

You can copy removed templates to your own codebase or rewrite the templates using standard HTML. Ensure that the new HTML structure matches the functionality provided by the Soy template.

If you decide to rewrite templates, update your JavaScript code to work with the new HTML. Ensure that any dynamic data binding or event handling is correctly implemented.

Removed templates are:

aui.buttons.splitButton
aui.dropdown2.dropdown2
aui.dropdown2.itemGroup
aui.dropdown2.itemList
aui.dropdown2.menuCheckbox
aui.dropdown2.menuLink
aui.dropdown2.menuRadio
aui.expander.revealText
aui.form.emailField
aui.form.fileField
aui.form.formDescription
aui.form.searchField
aui.form.telephoneField
aui.form.urlField
aui.form.valueField
aui.inlineDialog2.trigger
aui.toolbar2.item
aui.toolbar2.toolbar2

Example migration of random template from the rarely used group:

Web-resources

This have very little usage and are most often an alias for a different web-resource.

Removed web-resource	Replacement
`ajs-gadgets`	`com.atlassian.gadgets.publisher:ajs-gadgets`
`ajs-gadgets-base`	`com.atlassian.gadgets.publisher:ajs-gadgets`
`aui-experimental-badge`	`com.atlassian.auiplugin:aui-badge`
`aui-experimental-data-handlers`	`com.atlassian.auiplugin:aui-progressive-data-set`
`aui-experimental-devtools-iconfont`	`com.atlassian.auiplugin:aui-iconography` for the markup pattern and all of AUI's defined iconography, or just `com.atlassian.auiplugin:aui-icon` for the markup pattern
`aui-experimental-dropdown2`	`com.atlassian.auiplugin:aui-dropdown2`
`aui-experimental-labels`	`com.atlassian.auiplugin:aui-labels`
`aui-experimental-lozenge`	`com.atlassian.auiplugin:aui-lozenge`
`aui-experimental-soy-templates-2`	`com.atlassian.auiplugin:soy`
`aui-experimental-toolbar2`	`com.atlassian.auiplugin:aui-toolbar2`
`aui-format`	`com.atlassian.plugins.atlassian-plugins-webresource-plugin:i18n`. Please also convert from using the AJS global variable to the AMD module, i.e. `require('wrm/i18n')`
`aui-header-async`	`com.atlassian.auiplugin:aui-header`
`aui-header-unresponsive`	None, all header usages are async now
`aui-link`	None, this is now included in the base AUI styles
`aui-page-suite`	This was a group web-resource that included others, you should replace it with only what is used: `com.atlassian.auiplugin:aui-reset` `com.atlassian.auiplugin:aui-page-typography` `com.atlassian.auiplugin:aui-page-layout` `com.atlassian.auiplugin:aui-avatar` `com.atlassian.auiplugin:aui-header` `com.atlassian.auiplugin:aui-navigation` `com.atlassian.auiplugin:aui-page-header`
`aui-trigger`	None, it's only used internally in AUI
`event`	`com.atlassian.auiplugin:aui-event-bus`
`icons`	`com.atlassian.auiplugin:aui-iconography`
`internal-deprecated-cookie`	Bundle your own cookie management library, in the meantime `com.atlassian.auiplugin:cookie` can be used.
`internal-deprecated-dialog1`	Migrate to Dialog2, in the meantime `com.atlassian.auiplugin:dialog` can be used.
`internal-deprecated-inline-dialog1`	Migrate to Inline Dialog 2, in the meantime `com.atlassian.auiplugin:inline-dialog` can be used.
`internal-deprecated-jquery-spin`	`com.atlassian.auiplugin:aui-spinner`
`internal-deprecated-jquery-throbber`	`com.atlassian.auiplugin:aui-spinner`
`internal-jquery-ui-partial`	This was a group web-resource that included others, you should replace it with only what is used: `com.atlassian.auiplugin:jquery-ui-draggable` `com.atlassian.auiplugin:jquery-ui-focusable` `com.atlassian.auiplugin:jquery-ui-mouse` `com.atlassian.auiplugin:jquery-ui-plugin` `com.atlassian.auiplugin:jquery-ui-scroll-parent` `com.atlassian.auiplugin:jquery-ui-sortable` `com.atlassian.auiplugin:jquery-ui-widget`
`internal-vendor-backbone`	None, bundle your own copy of Backbone. Only DC product teams can use `com.atlassian.auiplugin:internal-vendor-backbone`
`internal-vendor-underscore`	None, bundle your own copy.
`jquery-throbber`	`com.atlassian.auiplugin:aui-spinner`
`jquery-ui-interactions`	This was a group web-resource that included others, you should replace it with only what is used: `com.atlassian.auiplugin:jquery-ui-droppable` `com.atlassian.auiplugin:jquery-ui-resizable` `com.atlassian.auiplugin:jquery-ui-selectable`
`jquery-ui-other`	This was a group web-resource that included others, you should replace it with only what is used: `com.atlassian.auiplugin:jquery-ui-position` `com.atlassian.auiplugin:jquery-ui-interactions`
`keyboardshortcuts`	`com.atlassian.auiplugin:aui-keyboard-shortcuts`
`keycode`	`com.atlassian.auiplugin:aui-key-code`
`layer`	`com.atlassian.auiplugin:aui-layer`
`table`	`com.atlassian.auiplugin:aui-table`

Upgraded dependencies

jQuery form

jquery-form is upgraded to 4.3.0 from 2.67.0

jQuery UI

From AUI 10.0.0-M09, jquery-ui is upgraded to 1.14.1 from 1.13.3

For reference, see the official release notes, upgrade guide, and changelog

AUI only exposes part of jQuery UI and thus only some breaking changes are relevant. The following APIs were removed as part of dropping support for IE.

Removed API	Replacement
`$.ui.ie`	`false` - AUI does not support IE
`$.ui.safeActiveElement`	`document.activeElement`
`$.ui.safeBlur('.selector')`	`$('.selector').trigger('blur')`

Removed dependencies

Tipsy

Tipsy was a jQuery tooltip plugin that is no longer maintained. Since 9.2, AUI has been using popperjs (now Floating UI) internally. With this we're removing the tipsy web-resource from AUI. We recommend you bundle your own version of Floating UI or some alternative. This will help avoid conflicts with other plugins on the same page and allow you to perform upgrades at your own pace.

Design tokens are auto-initialised

Design tokens and the "light" and "dark" themes built on those are automatically initialised and bundled with AUI now that original theme is gone.

Only load the aui-design-tokens-base-themes-css web-resource when the rest of AUI is not used as it will double load the same code.
Remove any usage of the aui-design-tokens-base-themes web-resource as it's not needed.
Continue using setGlobalTheme and updating iframes, this is not replaced.