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 fo 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 slid 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.

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 v-slot: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 v-slot: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.

<template>
  <div>
    <b-button v-b-toggle.sidebar-backdrop>Toggle Sidebar</b-button>
    <b-sidebar
      id="sidebar-backdrop"
      title="Sidebar with backdrop"
      backdrop
      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-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 prefered 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.

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.

Component reference

v2.10.0+

View source

<b-sidebar> Properties
<b-sidebar> v-model
<b-sidebar> Slots
<b-sidebar> Events

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

Property	Event
`visible`	`change`

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

Event	Arguments	Description
`change`	`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`
`shown`		Emitted when the sidebar has opened
`hidden`		Emitted when the sidebar has been hidden

Importing individual components

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

Component	Named Export	Import Path
`<b-sidebar>`	`BSidebar`	`bootstrap-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
`SidebarPlugin`	`bootstrap-vue`

This plugin also automatically includes the following plugins:

VBTogglePlugin

Example:

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

Overview

Styling

Title

Placement

Variants

Shadow

Borders

Width

Padding

Disable slide transition

Z-index

Scoped default slot

Header

Hiding the default header

Footer

Lazy rendering

Backdrop

Visibility control

`v-b-toggle` directive

`v-model`

Closing on $route change

Events

Accessibility

Implementation notes

See also

Component reference

`<b-sidebar>`

Properties

`v-model`

Slots

Events

Importing individual components

Importing as a Vue.js plugin

Overview

Styling

Title

Placement

Variants

Shadow

Borders

Width

Padding

Disable slide transition

Z-index

Scoped default slot

Header

Hiding the default header

Footer

Lazy rendering

Backdrop

Visibility control

v-b-toggle directive

v-model

Closing on $route change

Events

Accessibility

Implementation notes

See also

Component reference

Properties

v-model

Slots

Events

Importing individual components

Importing as a Vue.js plugin

`v-b-toggle` directive

`v-model`

`v-model`