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
Included in AUI core?	Not in core You must explicitly require the web resource key.
Web resource key:	`com.atlassian.auiplugin:aui-sidebar`
AMD Module key:	N/A
General API status:	5.6.3
Depends on:	jQuery

Code

Basic usage (HTML)

AUI Sidebar is meant to sit within the main #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".

999

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.

More actions Summary

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.

Issues

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.

More actions

999

Issues

Soy template usage

Sidebar page layout

Breadcrumbs or subtitle

Large avatar (eg project or space landing page)

Sidebar page layout

Breadcrumbs or subtitle

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

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.

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

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.

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.