Sidebar

Otherwise known as off-canvas or a side drawer, BootstrapVue's custom <b-sidebar> component is a fixed-position toggleable slide out box, which can be used for navigation, menus, details, etc. It can be positioned on either the left (default) or right of the viewport, with optional backdrop support.

Available in BootstrapVue since v2.10.0

Overview

You can place almost any content inside the <b-sidebar> optionally scoped default slot, such as text, buttons, forms, images, or vertical navs.

The component supports a header and built in close button, of which you can optionally disable and provide your own header (if needed), and can be easily toggled with our v-b-toggle directive.

The component has minimal default styling, which provides you with great flexibility in laying out the content of the sidebar.

<template>
  <div>
    <b-button v-b-toggle.sidebar-1>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-1" title="Sidebar" shadow>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar.vue -->

If the content is taller than the available viewport height, vertical scrolling will automatically be enabled via CSS on the body of the sidebar.

Styling

Several props are provided for controlling the appearance of the sidebar.

Title

Sidebars should have a title (specifically for accessibility reasons). Easily set the title that appears in the header either via the title prop or the title slot. Note the title slot takes precedence over the title prop.

If the no-header prop is set, then neither the title prop or title slot have any effect.

If you do not provide a title, use either the aria-label or aria-labelledby props to provide an accessible title for the sidebar. See the Accessibility section below for additional details.

Placement

By default the sidebar will be placed on the left side of the viewport. Set the right prop to true to have the sidebar appear on the right side of the viewport.

<template>
  <div>
    <b-button v-b-toggle.sidebar-right>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-right" title="Sidebar" right shadow>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-right.vue -->

Variants

Use the props bg-variant and text-variant to control the theme color variant of the background and text, respectively. Alternatively, you can apply styles or classes to specify the background and text colors.

<template>
  <div>
    <b-button v-b-toggle.sidebar-variant>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-variant" title="Sidebar" bg-variant="dark" text-variant="light" shadow>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-variant.vue -->

The standard Bootstrap theme variants are 'white', 'light', 'dark', 'primary', 'secondary', 'success', 'danger', 'warning', and 'info'.

The default background variant is 'light' and the default text variant is 'dark'.

Shadow

Prefer a sidebar with a backdrop shadow? Set the shadow prop to either boolean true for a medium shadow, 'sm' for a small shadow, or 'lg' for a larger shadow. Set it to false (the default) for no shadow.

Borders

By default, <b-sidebar> has no borders. Use border utility classes to add border(s) to <b-sidebar> (via the sidebar-class prop 2.12.0+), or use CSS style overrides.

<template>
  <div>
    <b-button v-b-toggle.sidebar-border>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-border" sidebar-class="border-right border-danger">
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-border.vue -->

Width

By default the width of <b-sidebar> is set to 320px (100% on 'xs' screens). Simply provide a value via the width prop (i.e. '180px', '20em', etc.) to override this default. The max width is set to 100% via CSS.

Padding

The sidebar by default has no padding. You can apply padding utility classes to the component, or margin/padding utility classes to the content of the sidebar.

Disable slide transition

By default the sidebar will use a sliding transition when showing and hiding. You can disable the slide transition via the no-slide prop.

Note: The BootstrapVue defined transition effect of this component is dependent on the prefers-reduced-motion media query. See the reduced motion section of our accessibility documentation for additional details.

When disabling the slide transition, the fade transition of the optional backdrop will also be disabled.

Z-index

The sidebar has a default z-index defined in SCSS/CSS. In some situations you may need to use a different z-index to ensure the sidebar appears over or under other content. You can do so either via CSS styles, or via the z-index prop.

Scoped default slot

The default slot allows you to provide the body content for your sidebar. It is optionally scoped. The examples in the following sections demonstrate the use of the default slot scope

You can apply arbitrary classes to the body section via the body-class prop.

By default, <b-sidebar> has a header with optional title and a close button. You can supply a title via the title prop, or via the optionally scoped slot title.

If you want to provide a completely custom header, you can use the optionally scoped header slot.

You can apply arbitrary classes to the header section via the header-class prop, to override the default padding, etc.

Hiding the default header

You can disable the default header (including the close button) via the no-header prop. Note that you will need to provide a method of closing the sidebar. The default slot is scoped, which includes a hide() method that can be used to close the sidebar.

<template>
  <div>
    <b-button v-b-toggle.sidebar-no-header>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-no-header" aria-labelledby="sidebar-no-header-title" no-header shadow>
      <template #default="{ hide }">
        <div class="p-3">
          <h4 id="sidebar-no-header-title">Custom header sidebar</h4>
          <p>
            Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
            in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
          </p>
          <nav class="mb-3">
            <b-nav vertical>
              <b-nav-item active @click="hide">Active</b-nav-item>
              <b-nav-item href="#link-1" @click="hide">Link</b-nav-item>
              <b-nav-item href="#link-2" @click="hide">Another Link</b-nav-item>
            </b-nav>
          </nav>
          <b-button variant="primary" block @click="hide">Close Sidebar</b-button>
        </div>
      </template>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-no-header.vue -->

<b-sidebar> provides a footer slot (optionally scoped), to allow you to provide content that appears at the bottom of the sidebar. The footer slot is scoped, which includes a hide() method that can be used to close the sidebar.

<template>
  <div>
    <b-button v-b-toggle.sidebar-footer>Toggle Sidebar</b-button>
    <b-sidebar id="sidebar-footer" aria-label="Sidebar with custom footer" no-header shadow>
      <template #footer="{ hide }">
       <div class="d-flex bg-dark text-light align-items-center px-3 py-2">
        <strong class="mr-auto">Footer</strong>
        <b-button size="sm" @click="hide">Close</b-button>
       </div>
      </template>
      <div class="px-3 py-2">
        <p>
          Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
          in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
        </p>
        <b-img src="https://picsum.photos/500/500/?image=54" fluid thumbnail></b-img>
      </div>
    </b-sidebar>
  </div>
</template>

<!-- b-sidebar-footer.vue -->

You can apply arbitrary classes to the footer section via the footer-class prop.

Lazy rendering

In some instances, you may not want the content rendered when the sidebar is not visible. Simply set the lazy prop on <b-sidebar>. When lazy is true, the body and optional footer will not be rendered (removed from DOM) whenever the sidebar is closed.

Backdrop

2.12.0+

Add a basic backdrop when the side bar is open via the backdrop prop. When set to true, the sidebar will show an opaque backdrop. Clicking on the backdrop will close the sidebar, unless the no-close-on-backdrop prop is set to true.

Optionally (as of BootstrapVue v2.15.0+) you can use the backdrop-variant prop to control the theme color variant of the backdrop. The default backdrop variant is dark.

<template>
  <div>
    <b-button v-b-toggle.sidebar-backdrop>Toggle Sidebar</b-button>

    <b-sidebar
      id="sidebar-backdrop"
      title="Sidebar with backdrop"
      :backdrop-variant="variant"
      backdrop
      shadow
    >
      <div class="px-3 py-2">
        <b-form-group label="Backdrop variant" label-for="backdrop-variant">
          <b-form-select id="backdrop-variant" v-model="variant" :options="variants"></b-form-select>
        </b-form-group>
      </div>
    </b-sidebar>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        variant: 'dark',
        variants: [
          'transparent',
          'white',
          'light',
          'dark',
          'primary',
          'secondary',
          'success',
          'danger',
          'warning',
          'info',
        ]
      }
    }
  }
</script>

<!-- b-sidebar-backdrop.vue -->

Note that when the sidebar is open, it may still be possible to scroll the body (unlike the behaviour of modals). When the backdrop in enabled, focus constraint will attempt to keep focus within the sidebar. Note that in rare circumstances it might be possible for users to move focus to elements outside of the sidebar.

Visibility control

v-b-toggle directive

Using the v-b-toggle directive is the preferred method for opening the sidebar, as it automatically handles applying the aria-controls and aria-expanded accessibility attributes on the trigger element.

The majority of examples on this page use the v-b-toggle directive.

v-model

The v-model reflects the current visibility state of the sidebar. While it can be used to control the visibility state of the sidebar, it is recommended to use the v-b-toggle directive to show the sidebar for accessibility reasons. If you do use the v-model to show the sidebar, you should place the aria-controls="id" attribute (where id is the ID of the sidebar) on the trigger element, and also set the aria-expanded attribute (also on the trigger element) to either the string 'true' (if the sidebar is open) or 'false' (if the sidebar is closed).

The v-model is internally bound to the visible prop, and the change event updates the v-model.

Closing on $route change

By default, <b-sidebar> will close itself when the $route changes (full path including query and hash). This can be particularly handy if the sidebar is placed outside of your <router-view> and is used for navigation.

You can disable this behaviour by setting the no-close-on-route-change prop to true.

Events

The sidebar will emit the shown event once the sidebar has opened, and the hidden event when the sidebar has closed.

The change event is used to update the v-model and is emitted whenever the visibility state of the sidebar changes.

Accessibility

<b-sidebar> provides several accessibility features.

When the sidebar is opened, the entire sidebar will receive focus, which is desirable for screen reader and keyboard-only users. When the sidebar is closed, the element that previously had focus before the sidebar was opened will be re-focused.

In some circumstances, you may need to disable the enforce focus feature completely. You can do this by setting the prop no-enforce-focus, although this is generally discouraged for accessibility reasons.

When the sidebar is open, users can press Esc to close the sidebar. To disable this feature, set the no-close-on-esc prop to true. with the backdrop enabled, you can use the prop no-close-on-backdrop to disable the close on backdrop click feature.

When the backdrop prop is true, the sidebar will attempt to constrain focus within the sidebar, and the sidebar will have the attribute aria-modal="true" set.

When you have hidden the header, or do not have a title for the sidebar, set either aria-label to a string that describes the sidebar, or set aria-labelledby to an ID of an element that contains the title. When using the lazy prop and you do not have a header, use the aria-label prop to provide an appropriate string to label the sidebar.

Implementation notes

BootstrapVue's custom SCSS/CSS is required for proper styling, and positioning of the sidebar.

The Bootstrap v4 background ('bg-*') and text ('text-*') utility classes are used for controlling the background and font color, respectively.

Some of the default styling for <b-sidebar> can be customized via the use of SASS variables. Refer to the theming documentation for additional details.

See also

Component reference

<b-sidebar>

v2.10.0+

Properties

All property default values are globally configurable.

Property
(Click to sort ascending)
Type
(Click to sort ascending)
Default
Description
aria-label
StringSets the value of `aria-label` attribute on the rendered element
aria-labelledby
StringThe ID of the element that provides a label for this component. Used as the value for the `aria-labelledby` attribute
backdrop
v2.12.0+
BooleanfalseWhen `true`, shows a backdrop when the sidebar is open
backdrop-variant
v2.15.0+
String'dark'Theme variant color for the backdrop of the sidebar. Defaults to 'dark'
bg-variant
String'light'Theme variant color for the background of the sidebar
body-class
Array or Object or StringClass, or classes, to apply to the body (default slot) of the sidebar
close-label
String`aria-label` to apply to the built-in close button. Defaults to 'Close'
footer-class
Array or Object or StringClass, or classes, to apply to the optional `footer` slot
footer-tag
v2.22.0+
String'footer'Specify the HTML tag to render instead of the default tag for the footer
header-class
Array or Object or StringClass, or classes, to apply to the built in header. Has no effect if prop `no-header` is set
header-tag
v2.22.0+
String'header'Specify the HTML tag to render instead of the default tag for the footer
id
StringUsed to set the `id` attribute on the rendered content, and used as the base to generate any additional element IDs as needed
lazy
BooleanfalseWhen set to `true`, the content of the sidebar will only be rendered while the sidebar is open
no-close-on-backdrop
v2.12.0+
BooleanfalseWhen set to `true`, disables closing the sidebar when the user clicks on the backdrop. Requires that the prop `backdrop` be set
no-close-on-esc
BooleanfalseWhen set to `true`, disables closing the sidebar when the user presses ESC
no-close-on-route-change
BooleanfalseWhen set to `true`, disables closing of the sidebar on route change
no-enforce-focus
v2.17.0+
BooleanfalseDisables the enforce focus routine which maintains focus inside the sidebar
no-header
BooleanfalseWhen set to `true` disables rendering of the default header (including close button)
no-header-close
BooleanfalseWhen set to `true` disables rendering of the header close button
no-slide
BooleanfalseWhen set, disables the default sliding animation
right
BooleanfalseWhen `true`, positions the sidebar on the right of the viewport
shadow
Boolean or StringfalseSet to boolean `true` for medium shadow, 'sm' for small shadow, 'lg' for large shadow, or boolean `false` for no shadow. Default is no shadow
sidebar-class
v2.12.0+
Array or Object or StringClass, or classes, to apply to the sidebar content wrapper
tag
String'div'Specify the HTML tag to render instead of the default tag
text-variant
String'dark'Theme variant color for the text of the sidebar
title
StringText content to place in the default header. The `title` slot takes precedence
visible
v-model
BooleanfalseWhen `true`, opens the sidebar. This is the `v-model`
width
StringCSS width for the sidebar. Defaults to '320px' as defined by SCSS/CSS
z-index
Number or StringSpecify an arbitrary z-index value to override the value defined by SCSS/CSS

v-model

Property
Event
visiblechange

Slots

Name
Scoped
Description
default Content to place in the body of the sidebar
footer Content to place in the optional footer
header v2.21.0+Content to place in the header
header-close NoContent of the header close button. Defaults to `<b-icon-x>`
title Content to place in the title of the built-in header. Takes precedence over the `title` prop

Events

Event
Arguments
Description
change
  1. visible - `true` if the sidebar is open, `false` if it is closed (or in the process of closing)
Emitted whenever the visibility of the sidebar changes. Used to update the `v-model`
hidden Emitted when the sidebar has been hidden
shown Emitted when the sidebar has opened

Importing individual components

You can import individual components into your project via the following named exports:

Component
Named Export
Import Path
<b-sidebar>BSidebarbootstrap-vue

Example:

import { BSidebar } from 'bootstrap-vue'
Vue.component('b-sidebar', BSidebar)

Importing as a Vue.js plugin

This plugin includes all of the above listed individual components. Plugins also include any component aliases.

Named Export
Import Path
SidebarPluginbootstrap-vue

This plugin also automatically includes the following plugins:

  • VBTogglePlugin

Example:

import { SidebarPlugin } from 'bootstrap-vue'
Vue.use(SidebarPlugin)