Toolbar2 upgrade guide

Ask a question

This page is a guide to upgrading from the Toolbar 1 API to the new API.

Toolbar 2

Only AUI buttons are supported

Toolbar 1 supported Dropdown 1, <aui-dropdown-menu>, buttons, anchors and inputs. Toolbar 2 only supports AUI buttons (which includes <aui-dropdown-menu> and link buttons).

It is easiest to starting by upgrading the Dropdown component.

If you need to support more, you can use a flex or grid layout generator, e.g. Angry tools - CSS Flex Layout.

Initialisation

Toolbar is pure CSS and is loaded via web-resource dependencies. It should be loaded at the same time as HTML is put on the page to avoid layout shift.

To migrate, find all instances of com.atlassian.auiplugin:toolbar and replace it with com.atlassian.auiplugin:aui-toolbar2.

HTML changes

  1. Replace the aui-toolbar class with aui-toolbar2
  2. Add the role="toolbar" attribute to the parent element
  3. Add a <div class="aui-toolbar2-inner"> element
  4. Replace the toolbar-split toolbar-split-row classes with the new row class aui-toolbar2-group
  5. Replace the old side alignment toolbar-split toolbar-split-left classes with the aui-toolbar2-primary class
  6. Replace the old side alignment toolbar-split toolbar-split-right classes with the aui-toolbar2-secondary class
  7. Replace <ul class="toolbar-group"> with <div class="aui-buttons"> elements
  8. Remove the <li class="toolbar-item"> wrapper elements
Old API New API