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.

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.

html

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

html

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

html

<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 <span class="badge badge-secondary">2.12.0+</span>), or use CSS style overrides.

html

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

html

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

html

<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

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.

html

<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 <kbd>Esc</kbd> 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.

Sidebar

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

Sidebar

Sidebar

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

`v-b-toggle` directive

`v-model`