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.

Demo code
Result

AUI Sidebar

  1. This is a really really long title for whatever this is
Settings
​x
 
<div id="content">
    <!-- AUI Sidebar -->
    <div class="aui-sidebar">
        <div class="aui-sidebar-wrapper">
            <div class="aui-sidebar-body">
​
                <!-- AUI Page Header pattern placed here -->
                <div class="aui-page-header">
                    <div class="aui-page-header-inner">
                        <div class="aui-page-header-image">
                            <span class="aui-avatar aui-avatar-project aui-avatar-large">
                                <span class="aui-avatar-inner">
                                    <img src="images/avatar-project.svg" alt="" role="presentation" />
                                </span>
                            </span>
                            
                        </div>
                        <div class="aui-page-header-main">
                            <h1>
                                AUI Sidebar
                            </h1>
                            <ol class="aui-nav aui-nav-breadcrumbs">
                                <li>
                                    <a href="#"><span class="aui-nav-item-label">This is a really really long title for whatever this is</span></a>
                                </li>
                            </ol>
                        </div>
                    </div>
                </div>
​
                <!-- AUI Navigation patterns placed here, make sure the aria-label describes the content of your nav well -->
                <nav class="aui-navgroup aui-navgroup-vertical" aria-label="Sidebar navigation">
                    <div class="aui-navgroup-inner">
​
                        <!-- A Sidebar group will collapse into a single trigger icon when sidebar is collapsed -->
                        <!-- The 'actions' sidebar group type will be styled differently from normal groups when sidebar is collapsed -->
                        <div class="aui-sidebar-group aui-sidebar-group-actions">
​
                            <!-- the AUI Nav heading will be used as the tooltip text -->
                            <div class="aui-nav-heading" title="Actions">
                                <strong>Actions</strong>
                            </div>
​
                            <!-- If a sidebar group does not have a nav heading, then the aui-nav's title attribute will be used
                                 for the tooltip for the group -->
                            <ul class="aui-nav" title="Page actions">
                                <li>
                                    <a class="aui-nav-item" href="#" title="Edit">Edit</a>
                                </li>
                                <li>
                                    <a class="aui-nav-item" href="#" title="View">View</a>
                                </li>
                                <li>
                                    <a class="aui-nav-item" href="#" title="Share">Share</a>
                                </li>
                            </ul>
                        </div>
​
                        <!-- A "Tier One" Sidebar group will display all of its nav items, but all nav items MUST have an AUI Icon
                             which will be used when the sidebar is collapsed -->
                        <div class="aui-sidebar-group aui-sidebar-group-tier-one">
​
                            <!-- in a "Tier One" Sidebar group, AUI Nav heading is ignored, and each nav item's label will be used
                                 as the tooltip text instead -->
                            <div class="aui-nav-heading" title="Stuff">
                                <strong>Simple Nav</strong>
                            </div>
​
                            <ul class="aui-nav">
                                <li class="aui-nav-selected">
​
                                    <!-- "selected" Nav items may strictly require or forbid anchoring, depending on the context of use. See "Design Patterns - current and selected items" page for details -->
                                    <a class="aui-nav-item" href="#info-content">
                                        <!-- "selected" Nav items may strictly require or forbid additional assistive labels supporting visually impaired users. See "Design Patterns - current and selected items" page for details -->
                                        <span class="assistive">Selected item:</span>
​
                                        <!-- "Tier One" navigation items MUST have an AUI Icon before the text label -->
                                        <span class="aui-icon aui-icon-small aui-iconfont-info"></span>
​
                                        <!-- "Tier One" Nav items labels also need an extra SPAN around them with the aui-nav-item-label class -->
                                        <span class="aui-nav-item-label">Summary</span>
                                    </a>
​
                                </li>
                                <li>
                                    <a class="aui-nav-item" href="#" title="This is a really really long title for whatever this is">
                                        <span class="aui-icon aui-icon-small aui-iconfont-details"></span>
                                        <span class="aui-nav-item-label">Issues</span>
                                    </a>
                                </li>
                                <li>
                                    <a class="aui-nav-item" href="#">
                                        <span class="aui-icon aui-icon-small aui-iconfont-jira-completed-task"></span>
                                        <span class="aui-nav-item-label">Road Map</span>
                                    </a>
                                </li>
                                <li>
                                    <a class="aui-nav-item" href="#">
                                        <span class="aui-icon aui-icon-small aui-iconfont-time"></span>
                                        <span class="aui-nav-item-label">Versions</span>
                                    </a>
                                </li>
                                <li>
                                    <a class="aui-nav-item" href="#">
                                        <span class="aui-icon aui-icon-small aui-iconfont-devtools-submodule"></span>
                                        <span class="aui-nav-item-label">Components</span>
                                    </a>
                                </li>
                                <li>
                                    <a class="aui-nav-item" href="#">
                                        <span class="aui-icon aui-icon-small aui-iconfont-devtools-tag"></span>
                                        <span class="aui-nav-item-label">Labels</span>
                                    </a>
                                </li>
                            </ul>
                        </div>
                    </div>
                </nav>
            </div>
​
            <!-- Sidebar footer contains the expand/collapse trigger, and optionally a button or a dropdown with configuration settings -->
            <div class="aui-sidebar-footer">
                <a href="https://example.com" class="aui-button aui-button-subtle aui-sidebar-settings-button" title="Settings">
                    <span class="aui-icon aui-icon-small aui-iconfont-configure"></span>
                    <span class="aui-button-label">Settings</span>
                </a>
                <button class="aui-button aui-button-subtle aui-sidebar-toggle aui-sidebar-footer-tipsy" title="Collapse sidebar ( [ )">
                    <span class="aui-icon aui-icon-small aui-iconfont-chevron-double-left"></span>
                </button>
            </div>
        </div>
    </div>
    <!-- end AUI Sidebar -->
    <main class="aui-page-panel" id="main" role="main">
        <div class="aui-page-panel-inner">
            <div class="aui-page-panel-content">
                <!-- Page content goes here -->
            </div>
        </div>
    </main>
</div>

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".

 
<ul class="aui-nav">
    <li>
        <a class="aui-nav-item" href="#" title="This is a really really long title for whatever this is">
            <aui-badge>999</aui-badge>
            <span class="aui-icon aui-icon-small aui-iconfont-details"></span>
            <span class="aui-nav-item-label">Issues</span>
        </a>
    </li>
</ul>

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.

 
<ul class="aui-nav">
    <li>
        <a class="aui-nav-item" href="#">
            <span class="aui-nav-item-actions">More actions</span>
            <span class="aui-icon aui-icon-small aui-iconfont-info"></span>
            <span class="aui-nav-item-label">Summary</span>
        </a>
    </li>
</ul>

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.

 
<ul class="aui-nav">
    <li>
        <a class="aui-nav-item nested-parent nested-open" href="#">
            <span class="aui-nav-item-label">Issues</span>
        </a>
        <ul class="aui-nav" title="one">
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li aria-expanded="true">
                <a href="#" class="aui-nav-subtree-toggle">
                    <span class="aui-icon aui-icon-small aui-iconfont-expanded"></span>
                </a>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                <ul class="aui-nav" title="two">
                    <li>
                        <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                    </li>
                    <li>
                        <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                    </li>
                </ul>
                <div class="aui-nav-heading">
                    <strong>Queues</strong>
                </div>
                <ul class="aui-nav" title="three">
                    <li>
                        <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                    </li>
                    <li>
                        <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                    </li>
                </ul>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
        </ul>
    </li>
</ul>

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.

 
<ul class="aui-nav">
    <li>
        <a class="aui-nav-item" href="#" title="This is a really really long title for whatever this is">
            <span class="aui-nav-item-actions">More actions</span>
            <aui-badge>999</aui-badge>
            <span class="aui-icon aui-icon-small aui-iconfont-details"></span>
            <span class="aui-nav-item-label">Issues</span>
        </a>
    </li>
    <li aria-expanded="true">
        <a href="#" class="aui-nav-subtree-toggle">
            <span class="aui-icon aui-icon-small aui-iconfont-expanded"></span>
        </a>
        <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
        <ul class="aui-nav" title="one">
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li aria-expanded="false">
                <a href="#" class="aui-nav-subtree-toggle">
                    <span class="aui-icon aui-icon-small aui-iconfont-collapsed"></span>
                </a>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                <ul class="aui-nav" title="two">
                    <li>
                        <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                    </li>
                    <li>
                        <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
                    </li>
                </ul>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
            <li>
                <a class="aui-nav-item" href="#"><span class="aui-nav-item-label">Issues</span></a>
            </li>
        </ul>
    </li>
</ul>

Soy template usage

 
{call aui.sidebar.sidebar}
    {param headerContent}
        {call aui.page.pageHeader}
            {param content}
                {call aui.page.pageHeaderImage}
                    {param content}
                        {call aui.avatar.avatar}
                            {param size: 'large' /}
                            {param isProject: true /}
                            {param avatarImageUrl: 'images/avatar-project.svg' /}
                            {param accessibilityText: 'My awesome project' /}
                        {/call}
                    {/param}
                {/call}
                {call aui.page.pageHeaderMain}
                    {param content}
                        <h1>Sidebar page layout</h1>
                        <ol class="aui-nav aui-nav-breadcrumbs">
                            <li>
                                <a href="#">
                                    <span class="aui-nav-item-label">Breadcrumbs or subtitle</span>
                                </a>
                            </li>
                        </ol>
                    {/param}
                {/call}
            {/param}
        {/call}
    {/param}
    {param content}
        <!-- AUI Navigation goes here -->
    {/param}
    {param settingsButtonUrl: 'https://example.com' /}
    {param settingsText: 'Settings' /}
{/call}

Large avatar (eg project or space landing page)

 
{call aui.sidebar.sidebar}
    {param headerContent}
        {call aui.page.pageHeader}
            {param extraClasses: 'aui-sidebar-header-large' /} // add this extra class to the AUI Page Header
            {param content}
                {call aui.page.pageHeaderImage}
                    {param content}
                        {call aui.avatar.avatar}
                            {param size: 'xxxlarge' /}  // Set the avatar size to 'xxxlarge'
                            {param isProject: true /}
                            {param avatarImageUrl: 'images/avatar-project.svg' /}
                            {param accessibilityText: 'My awesome project' /}
                        {/call}
                    {/param}
                {/call}
                {call aui.page.pageHeaderMain}
                    {param content}
                        <h1>Sidebar page layout</h1>
                        <ol class="aui-nav aui-nav-breadcrumbs">
                            <li>
                                <a href="#">
                                    <span class="aui-nav-item-label">Breadcrumbs or subtitle</span>
                                </a>
                            </li>
                        </ol>
                    {/param}
                {/call}
            {/param}
        {/call}
    {/param}
    {param content}
        <!-- AUI Navigation goes here -->
    {/param}
    {param settingsButtonUrl: 'https://example.com' /}
    {param settingsText: 'Settings' /}
{/call}

JavaScript

 
var sidebar = AJS.sidebar('.aui-sidebar');
​
// Try to expand the sidebar.
if (sidebar.isCollapsed()) {
    sidebar.expand();
}
​
// Listen to collapse events.
sidebar.on('collapse-start', function () {
    console.log('Sidebar is collapsing!');
});
​
sidebar.on('collapse-end', function () {
    console.log('Sidebar is now collapsed!');
});
​
// Event delegation for custom interactions.
sidebar.$el.on('click', '.clone', function (e) {
    if (sidebar.isCollapsed()) {
        e.preventDefault();
        cloneDialog.show();
    }
});

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.

 
var sidebar = AJS.sidebar('.aui-sidebar');

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.

 
sidebar.expand();
collapse()

Collapses the sidebar.

Fires event listeners bound to the collapse event.

 
sidebar.collapse();
toggle()

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

Fires the relevant expand/collapse event listeners.

 
sidebar.toggle();
isCollapsed()

Returns a boolean indicating whether the sidebar is currently collapsed.
 
if (sidebar.isCollapsed()) {
    // ...
}
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.
 
// Is the sidebar in 'fly-out' mode?
return !sidebar.isCollapsed() && sidebar.isViewportNarrow();
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
 
var selector = sidebar.collapsedTriggersSelector();
sidebar.$el.on('click', selector, function (e) {
    if (!sidebar.isCollapsed()) {
        return;
    }
​
    // ...
});

Events

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

 
var sidebar = AJS.sidebar('.aui-sidebar');
var onCollapseEnd = function () { /* ... */ };
sidebar.on('collapse-end', onCollapseEnd);

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

 
sidebar.off('collapse-end', onCollapseEnd);  // Remove onCollapseEnd handler only.
sidebar.off('collapse-end');  // Remove all handlers for the event name.
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.
 
sidebar.on('expand-end', function () {
    console.log('Sidebar was expanded.');
});
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.
 
sidebar.on('collapse-end', function () {
    console.log('Sidebar was collapsed.');
});

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.
Older versions
Changelog
Getting started FAQ Ask a question Components Design Patterns Upgrade guides