Sidebar

Structure

Sidebar structure in main layout can be viewed in views/layouts/dashboard/sidebar.hbs .
It's mainly composed of optional .sidebar-section items and .nav.

They are wrapped inside a .sidebar-inner element:

html

<div class="sidebar sidebar-light sidebar-fixed expandable">
 <div class="sidebar-inner">

    <div class="sidebar-section">
        <!-- optional sidebar header, comes before .nav -->
    </div>

    <ul class="nav">
        <!-- sidebar items and submenus -->
    </ul>

    <div class="sidebar-section">
        <!-- optional sidebar footer -->
    </div>

 </div>
</div>

Item Structure

The .nav section is composed of .nav-item elements and has the following structure as you can view in views/layouts/_commons/sidebar-item.hbs:

html

<li class="nav-item">
  <a href="LINK" class="nav-link dropdown-toggle">

   <i class="nav-icon fa fa-user"> <!-- or material icon here, etc --> </i>

   <span class="nav-text fadeable"><!-- .fadeable only used for 1st level links -->
        <span>link title here</span>
        <span class="badge badge-primary" title="tooltip title">badge text</span>
   </span><!-- /.nav-text -->

    <b class="caret fa fa-angle-left rt-n90"></b>
  </a>

  <div class="submenu collapse hideable">
    <ul class="submenu-inner">
        <!-- repeat -->
    </ul>
 </div>
</li>

.nav-item can have open and/or active classes depending on its status and whether it has submenu, etc
.nav-link can have dropdown-toggle if it has a submenu sibling.
.nav-text elements in the top level menu should have .fadeable class for collapsed sidebar mode (explained below in expandable)
.caret indicates submenu. It can be a different direction, for example fa-angle-right rt-90 or custom icons:
- For custom carets you should add .d-style class to .nav-link as well as .collapsed if submenu is not open.

html

<a href="LINK" class="nav-link d-style dropdown-toggle collapsed">
  ....

  <b class="caret fa fa-plus d-collapsed"></b><!-- will be shown when submenu is closed -->
  <b class="caret fa fa-minus d-n-collapsed"></b><!-- will be shown when submenu is open -->
</a>

.submenu should have collapse and if it sould be open by default load, you need to add .show class as well.
.fadeable & .hideable classes are for collapsed sidebar mode (explained below in expandable)

Header & Footer

Sidebar can have custom headers and footers.
For example in default Dashboard there are shortcut buttons and search box but in Dashboard 2, there are there is user info, image and buttons.
Each header item is a sidebar-section-item. Please see views/layouts/dashboard/sidebar-header.hbs for more info:

html

<div class="sidebar-section">
   <div class="sidebar-section-item">
        <!-- shortcut buttons -->
   </div>

   <div class="sidebar-section-item">
        <!-- search box -->
   </div>
</div>

Or see views/layouts/dashboard-2/sidebar-header.hbs for another example.

Note that that fadeable, hideable and fadeinable classes are used in collapsed/minimized sidebar as explained later below.

Sidebar footer is similar and you can see examples in

views/layouts/dashboard/sidebar-footer.hbs and
views/layouts/dashboard-2/sidebar-footer.hbs

Scrollbars

In Ace's demo I'm only using native browser scrollbars as mentioned here but you can also use plugins.
Because of sidebar's structure, it's best to use native scrollbars so it performs better specially on mobile devices.

To enable scrollbars on sidebar, you should wrap the scrollable sections inside an element with data-ace-scroll attribute and .ace-scroll.flex-grow-1 class:

html

<div class="sidebar-inner">
 <div class="ace-scroll flex-grow-1" data-ace-scroll>
    <!-- scrollable content -->
 </div>
</div>

You can put sidebar headers or footers inside or outside of scrollable area:
Sidebar Scroll

html

<div class="sidebar-inner">
 <!-- sidebar header can be outside of it -->

 <div class="ace-scroll flex-grow-1" data-ace-scroll>
    <!-- sidebar header can be inside of it -->

    <!-- scrollable content -->

    <!-- sidebar footer can be inside of it -->
 </div>

 <!-- sidebar footer can be outside of it -->
</div>

Can be added to .sidebar to move sidebar to right (like in Two Menus page)

The following options (all false by default) can be passed to aceSidebar plugin when it initializes sidebar functionality on page load:

html

<div id="sidebar" class="sidebar sidebar-light sidebar-fixed" 
     data-swipe="true" data-gotoactive="true" data-dismiss="true">
 ...
</div>

`backdrop`

If true adds a backdrop when sidebar is displayed in mobile view

`dismiss`

If true when sidebar is displayed in mobile view, touching/clicking outside sidebar area will hide/dismiss it

`swipe`

If true you can swipe left to hide sidebar in mobile view :
Sidebar Backdrop and Swipe

`gotoactive`

When true if sidebar is fixed and has scrollbars, after page is loaded, sidebar is scrolled down so that .active item becomes visible:
Sidebar scroll to active

`subscroll`

Default is true and when sidebar is fixed and you click to open a submenu, sidebar will be scrolled down/up a little to bring submenu into view

`pullup`

If true when sidebar is fixed and collapsed and in hoverable (popup) mode, submenus are pulled up so that they don't get clipped by browser window. Note that you can also dynamically enable/disable this feature when needed:

$('#sidebar')
.on('collapsed.ace.sidebar', function() {
    if ($(this).hasClass('hoverable sidebar-fixed')) {
      $(this).aceSidebar('enableSubmenuPullup')
    }
})
.on('expanded.ace.sidebar', function() {
    $(this).aceSidebar('disableSubmenuPullup')
})

Submenu Pull up

Horizontal sidebar can be inserted right after .navbar or inside .main-content (like the Two menus example page).
By adding .sidebar-h you can have horizontal sidebar.
You should also add .sidebar-hover class to make submenus appear on mouse hover.

If you add .align-items-xl-end to .sidebar-inner or the .container element, the nav items won't be 100% height.
If you remove that, nav items will have 100% height.

html

<div class="sidebar sidebar-fixed sidebar-hover sidebar-h sidebar-top">
   <div class="sidebar-inner align-items-xl-end">
    ...
   </div>
</div>

You can have a .container element inside .sidebar-inner if you want to apply boxed layout to sidebar: Horizontal menu container

html

<div class="sidebar sidebar-fixed sidebar-hover sidebar-h">
   <div class="sidebar-inner align-items-xl-end">
      <div class="container container-plus px-0 d-flex flex-column flex-xl-row">
        ....
      </div>
   </div>
</div>

See views/layouts/horizontal/sidebar.hbs for more details.

If you want to change horizontal menu's height, you can do so by changing the value of horizontal-height in _sidebar-theme-variables.scss and rebuilding CSS.

There are also the following options available:

`.collapsed-h`

Add this to .sidebar for a more compact (collapsed) horizontal sidebar.
Also if there is a button to toggle (expand/collapse) sidebar, it should have the extra data-toggle-class attribute:

html

<button type="button" class="d-style btn btn-secondary" data-toggle="sidebar" data-target="#sidebar2"
    data-toggle-class="collapsed-h">
    <i class="fa fa-minus d-n-collapsed"></i>
    <i class="fa fa-plus d-collapsed"></i>
</button>

`.nav-fill`

Add this to .nav element to make it fill all the available space. You should also add .text-center to it.

`.nav-active-sm`

Add this to .nav so that the highlight border for active element is a bit smaller

`.nav-link-rounded`

Add this to .nav so that nav links have rounded corners on top. Useful only if nav doesn't have 100% height.

`.submenu-right`

Add this to a .nav-item and its submenu will be right aligned.

In horizontal menu, the last item's dropdown is also right aligned like this image:
Horizontal submenu last

If you don't want this, you can add an extra empty "li" after the last "li.nav-item"

`.fadeable-below`

Add this to .sidebar-section-item so that it appears below sidebar.
Also add .fadeable-center or .fadeable-right to center/right align it.

`.active-on-right`

Add to .nav to show the active highlight border on top

You can have a non-fixed navbar (remove .navbar-fixed) and a fixed (sticky) horizontal sidebar (add .sidebar-fixed).
You can also have fixed navbar only on small devices by adding .navbar-fixed-sm , .navbar-fixed-md , .navbar-fixed-lg or .navbar-fixed-xl to navbar.

Adding .sidebar-spaced will make .nav-item elements have some space from .sidebar.
In demo, this is used for sidebar-lightblue , sidebar-lightblue2 and sidebar-lightpurple themes but you can use it with other sidebar themes as well:

html

<div class="sidebar sidebar-color sidebar-dark sidebar-spaced">
    ...
</div>

Sidebar spaced

You can disable it by setting sidebar-spaced to false in scss/_variables.scss .
You can also change values for spaced sidebar by searching for spaced- variables in scss/_sidebar-themes-variables.scss .

Nav options

The .nav element can have the following options/classes:

`.has-active-border`

Adds highlight border on left of an active item.
In each sidebar theme, the color can be specified by modifying link-active-highlight-border in scss/_sidebar-themes-variables.scss.
See customizing sidebar themes for more info

`.active-on-right`

Will show the active highlight border on right.
Active On Top

`.active-on-top`

The active border will only be displayed for the 1st level item and not the items in submenus:
Active On Top

`.has-active-arrow`

The active item will have an arrow pointing to it:

html

<ul class="nav has-active-border has-active-arrow">
 ...
</ul>

<ul class="nav has-active-border active-on-top">
 ...
</ul>

If you don't want to use these options, you can disable them by setting their values to false in scss/ace-features.scss

Submenu Hover

You can have submenu elements appear on mouse hover by adding .sidebar-hover to .sidebar.
In that case, you should also set data-pullup to true for sidebar OR call enableSubmenuPullup function:

html

<div id="sidebar" class="sidebar sidebar-dark sidebar-color expandable sidebar-fixed" data-pullup="true" ...>
 ...
</div>

 $('#sidebar').aceSidebar('enableSubmenuPullup')

.sidebar-hover doesn't work with .sidebar-spaced

👉 There are 3 different collapsed sidebar modes, all enabled by default in demo.
But as you only need one in your app, you should disable the unwanted ones by setting them to false in scss/ace-features.scss and re-building ace.css.

Expandable

In expandable sidebar after being collapsed/minimized, when mouse hovers it, the sidebar will be expanded back to noraml full size without taking document space.

To enable it you should add the following classes:

.expandable for sidebar element

html

<div class="sidebar expandable">
   <div class="sidebar-inner">
    ....
   </div>
</div>

Use .fadeable for an element that should be faded out when sidebar is being collapsed. For example .nav-text should have this
.hideable for an element that should be hidden and take no space when sidebar is being collapsed. For example .submenu should have this

html

<ul class="nav">
    <li class="nav-item">
        <a href="#" class="nav-link dropdown-toggle">
            <span class="nav-text fadeable"> ... </span>
        </a>

        <div class="submenu hideable collapse">
            ...
        </div>
    </li>
</ul>

Use .fadeinable element will be shown when sidebar is collapsed.

html

<div class="sidebar-section">
    <div class="sidebar-section-item">
        <div class="fadeinable">
            <!-- show this when sidebar is collapsed -->
        </div>
        <div class="fadeable">
            <!-- show this when sidebar is expanded and will be faded out when collapsed -->
        </div>
    </div>
</div>

For example, you can make .nav-icon elements .fadeinable too and they will be hidden when sidebar is expanded (full size) and shown when collapsed:

html

<li class="nav-item">
 <a href="LINK" class="nav-link dropdown-toggle">
   <i class="nav-icon fadeinable fa fa-user ml-4"></i>
   <!-- or don't use .nav-icon class -->
   <i class="fadeinable fa fa-user"></i>
 </a>
 ...
</li>

.let-expanded: If you add this class to .sidebar.expandable and you collapse the sidebar using a toggle button that's inside the sidebar, sidebar will collapse but because mouse is inside it, it will remain expanded (as expected).
If you don't add this class to sidebar, sidebar will collapse anyway.

Hoverable

In hoverable sidebar after being collapsed/minimized, when mouse hovers an item, the item's text and submenu will be shown like a popup menu.

To enable it you should add the following classes:

.hoverable for sidebar element

html

<div class="sidebar hoverable">
    <div class="sidebar-inner">
    ....
    </div>
</div>

.fadeinable elements that are child of .sidebar-section-item will be shown when sidebar is collapsed
.fadeable elements that are child of .sidebar-section-item will be hidden when sidebar is collapsed and displayed when mouse hovers it
.fadeable-left , .fadeable-top , .fadeable-bottom classes can be added to .sidebar-section-item to specify where will the .fadeable appear when mouse hovers it:

html

<div class="sidebar-section">
    <div class="sidebar-section-item fadeable-top">
        <div class="fadeinable">
            <!-- show this when sidebar is collapsed -->
        </div>
        <div class="fadeable">
            <!-- show this when this sidebar is not collapsed / or when sidebar is collapsed and item is hovered -->
        </div>
    </div>
</div>

In that case, you should also set data-pullup to true for sidebar OR call enableSubmenuPullup function:

html

<div id="sidebar" class="sidebar sidebar-dark sidebar-color expandable sidebar-fixed" data-pullup="true" ...>
 ...
</div>

 $('#sidebar').aceSidebar('enableSubmenuPullup')

Hideable

Hideable sidebar will be hidden completely rather than being minimized

html

<div class="sidebar hideable">
    <div class="sidebar-inner">
    ....
    </div>
</div>

Toggler (desktop)

You can use any button or element for toggling. It should have data-toggle="sidebar" attribute:

html

<button type="button" class="btn btn-warning d-none d-xl-flex"
data-toggle="sidebar" data-target="#sidebar"
aria-controls="sidebar" aria-expanded="true" aria-label="Toggle sidebar">

  <i class="fa fa-bars"></i>

</button>

You can also call the toggle functions directly:

$('#sidebar').aceSidebar('toggle')
$('#sidebar').aceSidebar('collapse')
$('#sidebar').aceSidebar('expand')

Captions & Dividers

Inside .nav element you can have captions and dividers:
Caption & Divider

html

<ul class="nav">
  <li class="nav-item-caption">
     <span class="fadeable">MAIN</span>
     <span class="fadeinable">…</span>
   </li>
   <!-- or hide caption when collapsed -->
   <li class="nav-item-caption">
     <span class="hideable">MAIN</span>
   </li>
</ul>

If you set $collapsed-sidebar-caption-no-margin to true in ace-features.scss, when sidebar is collapsed, captions & dividers will have no margin-top or bottom:
Caption no margin

html

 <li class="nav-item"> ... </li>
 
 <li class="nav-item-divider"></li>

 <li class="nav-item-divider my-2 mx-0 hideable"></li>

 <li class="nav-item"> ... </li>

You can change the color of dividers and captions by modifying divider-color, caption-color, caption-size, etc in _sidebar-themes-variables.scss

Mobile View

Mobile view is applied in screen sizes below xl (1200px). You can add the following options:

backdrop , dismiss and swipe as described in sidebar options
.sidebar-top will make the sidebar start from top: 0px and not below navbar
.sidebar-push will push content area when sidebar is being displayed

html

<div class="sidebar sidebar-push sidebar-dark sidebar-color expandable">
    ...
</div>

Toggler (mobile)

You can use any button or element for toggling. It should have data-toggle-mobile="sidebar" attribute and be .collapsed by default:

html

<button type="button" class="btn btn-info d-flex d-xl-none collapsed"
data-toggle-mobile="sidebar" data-target="#sidebar"
aria-controls="sidebar" aria-expanded="false" aria-label="Toggle sidebar">

  <i class="fa fa-bars"></i>

</button>

You can also call the toggle functions directly:

$('#sidebar').aceSidebar('toggleMobile')
$('#sidebar').aceSidebar('show')
$('#sidebar').aceSidebar('hide')

There are some toggling buttons included in Ace using .btn-burger. For example .btn-burger.burger-arrowed is changed to this when sidebar is shown:

The following burger buttons are available:

.burger-arrowed
.burger-times the bars will become like times sign ×
.burger-minus the bars will become one line
.burger-compact the bars will become compact
.burger-steps the bars will become step like
.burger-dots there are no bars but dots instead

For these options, you should use the button with .static class and the child element should be a .bars element:

html

<button
      type="button" data-toggle-mobile="sidebar" data-target="#sidebar" aria-controls="sidebar" aria-expanded="false" aria-label="Toggle sidebar"
      class="btn btn-burger burger-compact static d-flex d-xl-none collapsed">

       <span class="bars"></span>

</button>

Themes

See Sidebar Themes

Javascript

Sidebar's functionality is enabled in aceSidebar plugin which is initialized on page load.
You can pass some options to it using data-* attributes as explained in sidebar options

Functions

The following functions are available:

toggle , collapse , expand
toggleMobile , show , hide
enableSubmenuPullup , disableSubmenuPullup

$('#sidebar').aceSidebar('collapse')

Events

The following events are available:

show , shown : triggered before/after sidebar is shown in mobile view
hide , hidden : triggered before/after sidebar is hidden in mobile view
expand : expanded : triggered before/after sidebar is expanded in desktop view
collapse : collapsed : triggered before/after sidebar is collapsed in desktop view

$('#sidebar').on('show.ace.sidebar', function(e) {
  // e.preventDefault();
})
$('#sidebar').on('collapsed.ace.sidebar', function(e) {
  // do something
})

Sidebar

Structure

Item Structure

Header & Footer

Scrollbars

Sidebar Options

`.sidebar-right`

`backdrop`

`dismiss`

`swipe`

`gotoactive`

`subscroll`

`pullup`

Horizontal sidebar

`.collapsed-h`

`.nav-fill`

`.nav-active-sm`

`.nav-link-rounded`

`.submenu-right`

`.fadeable-below`

`.active-on-right`

Spaced sidebar

Nav options

`.has-active-border`

`.active-on-right`

`.active-on-top`

`.has-active-arrow`

Submenu Hover

Collapsed Sidebar

Expandable

Hoverable

Hideable

Toggler (desktop)

Captions & Dividers

Mobile View

Toggler (mobile)

Themes

Javascript

Functions

Events