Sidebar

Ask a question

Summary

Sidebar component that contains page actions and navigation. Can be collapsed manually by the user by clicking, or automatically based on browser window resize

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-sidebar
AMD Module key: N/A
General API: 5.6.3

Code

Anatomy of a sidebar

AUI Sidebar is meant to sit within the #content section of the AUI Page Layout, before the aui-page-panel. See comments in example below for required markup patterns and CSS classes.

Sidebar navigation variations (HTML)

Various AUI Navigation options can be used within AUI Sidebar, and they will be styled correctly, however the ordering of the <span> elements within the <a> is important

Badges

The badge will show a number next to "Issues".

Nav item actions

The aui-nav-item-actions widget will be positioned on the right, but you will need to add your own dropdown functionality.

Nested navigation

Nested AUI Navigation is supported. The trigger elements need to have the nested-parent class If a expand / collapsed twixy is needed, use the aria-expanded Boolean attribute to change the twixy orientation.

The Kitchen Sink

AUI Badges can be used to display a count of items, and will be positioned on the right The element order of various nav item options is important otherwise the styles will not be applied correctly.

Soy template usage

Large avatar (eg project or space landing page)

JavaScript

Initialization

The sidebar element (.aui-sidebar) is automatically initialized on DOM ready, i.e., it requires no additional JavaScript code.

At DOM ready, if the sidebar is rendered (in markup) as expanded but the browser is too narrow, it is automatically collapsed (without animations). This will likely run prior to any other JavaScript code having had a chance to bind to the sidebar's collapse or expand events, so if you are interested in the initial state of the sidebar you may want to add a DOM ready handler that inspects isCollapsed().

The sidebar can be collapsed or expanded on initial page load by adding aui-page-sidebar and aui-sidebar-collapsed or aui-sidebar-expanded classes to the tag. The 'sidebar' layout type in the AUI Page Layout Soy template does this for you. This is to prevent a flash of the sidebar in an unexpected state, before the JavaScript executes and sets the state based on available screen width and/or user preference if it is stored by the host product.

Options

HTML attributes

There are a few configuration options that are expressed through markup on the main aui-sidebar container element

Class Description
aui-is-animated

Enables CSS transitions for the toggling of expanded/collapsed state.

Note that this has browser performance implications as it animates the main content area (and causes reflow/relayout) as well as the sidebar itself. YMMV.
Attribute Values Description
aria-expanded false | true Specifies if the sidebar is collapsed (false) or expanded (true) by default, overriding the auto-expand/collapse behaviour
data-aui-responsive false Specifies whether the sidebar should automatically collapse/expand based on browser width

Sidebar groups

AUI sidebar uses a div with the aui-sidebar-group class inside of the aui-navgroup/aui-navgroup-inner to group related sidebar nav items together. When the sidebar is in a collapsed state, each aui-sidebar-group will be represented by a single icon and the group's contents will be displayed in a fly-out menu.

There are two special sidebar groups – "Actions" and "Tier One".

The "Actions" sidebar group is typically used for action items that are contextual to the screen or section that the user is on. The Actions group will get a different different (ellipsis) icon and mouse hover/focus effect when the sidebar is collapsed, and should be the very first sidebar group in the sidebar, directly below the sidebar header and above normal navigation items. There should only be ONE aui-sidebar-group-actions group.

Tier One sidebar groups will display all navigation items within the group even when the sidebar is collapsed (normal sidebar groups will collapse into a single icon). While icons are optional for regular navigation items, Tier One navigation items must have an icon, otherwise there will be empty gaps in the sidebar where the icon should be.

Class Description
aui-sidebar-group-tier-one Specifies that the sidebar group is a "Tier One" group
aui-sidebar-group-actions Specifies that the sidebar group is the "Actions" group

Dividers

New in AUI 5.7.1

To insert a horizontal divider between AUI Navigation uls or aui-sidebar-groups, just use the <hr> element and it will be styled appropriately.

Soy params

There is a aui.sidebar.sidebar template that you can call with the following parameters which will render the correct HTML markup

Param Required Description
content Required

Main sidebar HTML content. Typically in the form of an AUI Vertical navigation.
headerContent Required

Sidebar header HTML content. Typically in the form of an AUI Page Header.
footerContent Required

Sidebar footer HTML content. Typically an AUI Button or Dropdown2. This will override the default settings button (see settingsButtonUrl and settingsText below).
settingsButtonUrl Optional

Link to direct the standard sidebar settings button. Must be used together with $settingsText for button to appear in sidebar footer.
settingsText Optional

Text to use for the standard sidebar settings button. Must be used together with $settingsUrl for button to appear in sidebar footer.
settingsTooltip Optional

Tooltip to display with the sidebar settings button, defaults to $settingsText if not set.
id Optional

ID for the sidebar container.
state Optional

String. 'collapsed', 'expanded' or left undefined. Used by AUI Sidebar to render the sidebar's initial state.
tagName Optional

HTML element for the sidebar container. Default is 'div'.
isResponsive Optional

Boolean. Whether the sidebar should automatically collapse/expand based on browser width. Default is true.
isResizable Optional

Boolean. Enables a draggable handle to allow the user to resize the sidebar. Default is false.
isAnimated Optional

Boolean. Enables animated transitions for Sidebar expanding and collapsing. Default is false.
extraClasses Optional

String or Object. CSS classes to add to the outermost (.aui-sidebar) element.
extraAttributes Optional

String or Object. Additional attributes to add to the outermost (.aui-sidebar) element.

JavaScript API

You can retrieve an instance of the sidebar via AJS.sidebar(selector) where selector is a jQuery selector string, jQuery collection, or an element.

Methods

Method Description Example Usage
expand()

Expands the sidebar. If the browser window is less than 1280px wide (see isViewportNarrow()), the expanded sidebar will be the 'fly-out' style that floats over your page content, rather than pushing it over to the right.

Fires event listeners bound to the expand event.

collapse()

Collapses the sidebar.

Fires event listeners bound to the collapse event.

toggle()

Expands the sidebar if it is currently collapsed; collapses it if it is currently expanded.

Fires the relevant expand/collapse event listeners.

isCollapsed()

Returns a boolean indicating whether the sidebar is currently collapsed.
isViewportNarrow()

Returns a boolean indicating whether the browser is narrow enough to trigger the auto collapsing behaviour when resizing the browser and 'fly-out' mode when the sidebar is expanded.
collapsedTriggersSelector()

Returns a jQuery selector string for the trigger elements when the sidebar is in a collapsed state, useful for delegated event binding.

When using this selector in event handlers, the element (this) will either be an <a> (when the trigger was a tier-one menu item) or an element with class aui-sidebar-group (for non-tier-one items).

You should check the value of isCollapsed() in your event handler

Events

You can listen to events triggered by the sidebar by calling the on() method:

Event handlers attached with the on() method can be removed with the off() method:

Event Description Example Usage
expand-start, expand-end

Fired when the sidebar is expanded.

One can distinguish between a user-initiated collapse and a browser resize collapse by checking the isResponsive attribute on the event object.

One can prevent sidebar from expanding by calling preventDefault() method on the expand-start event object.

One can determine whether the sidebar is in fly-out mode by checking isViewportNarrow() in the event handler.
collapse-start, collapse-end

Fired when the sidebar is collapsed.

One can prevent sidebar from collapsing by calling preventDefault() method on the collapse-start event object.

One can distinguish between a user-initiated collapse and a browser resize collapse by checking the isResponsive attribute on the event object.

If the sidebar has animation disabled, or the user has no animation support the *-end events will fire immediately after the changes have been made.