Offcanvas

Build hidden sidebars into your project for navigation, shopping carts, and more with a few classes and our JavaScript plugin.

How it works#

Offcanvas is a sidebar component that can be toggled via JavaScript to appear from the left, right, top, or bottom edge of the viewport. Buttons or anchors are used as triggers that are attached to specific elements you toggle, and data attributes are used to invoke our JavaScript.

The animation effect of this component is dependent on the prefers-reduced-motion media query.

Examples

Offcanvas components#

An offcanvas example that is automatically displayed is provided below (via.show on.offcanvas). A header with a close button and an optional body class for some initial padding are supported by Offcanvas. When practical, it is advised including offcanvas headers with dismiss actions or including a clear dismiss action.

<div class="offcanvas offcanvas-start show" tabindex="-1" id="offcanvas" aria-labelledby="offcanvasLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    Content for the offcanvas goes here. You can place just about any UX4G component or custom elements here.
  </div>
</div>

Live demo#

Use the buttons below to toggle the |.show class on an element with the .offcanvas class using JavaScript to show and hide an offcanvas element.

By default, .offcanvas conceals content
offcanvas .show displays information

Developers can use a button with the data-bs-target attribute or a link with the href attribute. The data-bs-toggle="offcanvas" is necessary in both situations.

<a class="btn btn-primary" data-bs-toggle="offcanvas" href="#offcanvasExample" role="button" aria-controls="offcanvasExample">
  Link with href
</a>
<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasExample" aria-controls="offcanvasExample">
  Button with data-bs-target
</button>

<div class="offcanvas offcanvas-start" tabindex="-1" id="offcanvasExample" aria-labelledby="offcanvasExampleLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasExampleLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
    </div>
    <div class="dropdown mt-3">
      <button class="btn btn-secondary dropdown-toggle" type="button" data-bs-toggle="dropdown">
        Dropdown button
      </button>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#">Action</a></li>
        <li><a class="dropdown-item" href="#">Another action</a></li>
        <li><a class="dropdown-item" href="#">Something else here</a></li>
      </ul>
    </div>
  </div>
</div>

RESULT

Link with href

Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.

Dark offcanvas #

Change the appearance of offcanvases with utilities to better match them to different contexts like dark navbars. Here we add .text-bg-dark to the .offcanvas and .btn-close-white to .btn-close for proper styling with a dark offcanvas. If you have dropdowns within, consider also adding .dropdown-menu-dark to .dropdown-menu.

<div class="bd-example bd-example-offcanvas p-0 bg-light overflow-hidden">
<div class="offcanvas offcanvas-start text-bg-dark" tabindex="-1" id="offcanvasDark" aria-labelledby="offcanvasDarkLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasDarkLabel">Offcanvas</h5>
    <button type="button" class="btn-close btn-close-white" data-bs-dismiss="offcanvasDark" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Place offcanvas content here.</p>
  </div>
</div>
</div>

Body scrolling #

Scrolling the <body> element is disabled when an offcanvas and its backdrop are visible. Use the data-bs-scroll attribute to enable <body> scrolling.

<div class="offcanvas offcanvas-start" data-bs-scroll="true" data-bs-backdrop="false" tabindex="-1" id="offcanvasScrolling" aria-labelledby="offcanvasScrollingLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasScrollingLabel">Offcanvas with body scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

RESULT

Try scrolling the rest of the page to see this option in action.

Body scrolling and backdrop #

You can also enable <body> scrolling with a visible backdrop.

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasWithBothOptions" aria-controls="offcanvasWithBothOptions">Enable both scrolling & backdrop</button>

<div class="offcanvas offcanvas-start" data-bs-scroll="true" tabindex="-1" id="offcanvasWithBothOptions" aria-labelledby="offcanvasWithBothOptionsLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasWithBothOptionsLabel">Backdrop with scrolling</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p>Try scrolling the rest of the page to see this option in action.</p>
  </div>
</div>

RESULT

Try scrolling the rest of the page to see this option in action.

Static backdrop #

When backdrop is set to static, the offcanvas will not close when clicking outside of it.

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#staticBackdrop" aria-controls="staticBackdrop">
  Toggle static offcanvas
</button>

<div class="offcanvas offcanvas-start" data-bs-backdrop="static" tabindex="-1" id="staticBackdrop" aria-labelledby="staticBackdropLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="staticBackdropLabel">Offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <div>
      I will not close if you click outside of me.
    </div>
  </div>
</div>

RESULT

I will not close if you click outside of me.

Responsive #

Added in v1.0.1

Responsive offcanvas classes hide content outside the viewport from a specified breakpoint and down. Above that breakpoint, the contents within will behave as usual. For example, .offcanvas-lg hides content in an offcanvas below the lg breakpoint, but shows the content above the lg breakpoint.

<button class="btn btn-primary d-lg-none" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasResponsive" aria-controls="offcanvasResponsive">Toggle offcanvas</button>

<div class="alert alert-info d-none d-lg-block">Resize your browser to show the responsive offcanvas toggle.</div>

<div class="offcanvas-lg offcanvas-end" tabindex="-1" id="offcanvasResponsive" aria-labelledby="offcanvasResponsiveLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasResponsiveLabel">Responsive offcanvas</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#offcanvasResponsive" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    <p class="mb-0">This is content within an <code>.offcanvas-lg</code>.</p>
  </div>
</div>

RESULT

Resize your browser to show the responsive offcanvas toggle.
Responsive offcanvas
This is content within an .offcanvas-lg.

Responsive offcanvas classes are available across for each breakpoint.

.offcanvas
.offcanvas-sm
.offcanvas-md
.offcanvas-lg
.offcanvas-xl
.offcanvas-xxl

Placement #

Offcanvas components cannot be placed by default; as a result, one of the modifier classes listed below must be added.

Offcanvas is positioned to the left of the viewport (as shown above) by .offcanvas-start
Offcanvas is positioned to the right of the viewport by offcanvas-end.
Offcanvas is positioned at the top of the viewport
Using offcanvas-top .offcanvas-bottom positions offcanvas at the viewport's base.

Try the top, right, and bottom examples out below.

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasTop" aria-controls="offcanvasTop">Toggle top offcanvas</button>

<div class="offcanvas offcanvas-top" tabindex="-1" id="offcanvasTop" aria-labelledby="offcanvasTopLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasTopLabel">Offcanvas top</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

RESULT

...

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasRight" aria-controls="offcanvasRight">Toggle right offcanvas</button>

<div class="offcanvas offcanvas-end" tabindex="-1" id="offcanvasRight" aria-labelledby="offcanvasRightLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasRightLabel">Offcanvas right</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body">
    ...
  </div>
</div>

RESULT

...

<button class="btn btn-primary" type="button" data-bs-toggle="offcanvas" data-bs-target="#offcanvasBottom" aria-controls="offcanvasBottom">Toggle bottom offcanvas</button>

<div class="offcanvas offcanvas-bottom" tabindex="-1" id="offcanvasBottom" aria-labelledby="offcanvasBottomLabel">
  <div class="offcanvas-header">
    <h5 class="offcanvas-title" id="offcanvasBottomLabel">Offcanvas bottom</h5>
    <button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>
  </div>
  <div class="offcanvas-body small">
    ...
  </div>
</div>

RESULT

...

Accessibility #

Since the offcanvas panel resembles a modal dialog conceptually, make sure to add aria-labelledby="..." to .offcanvas, referring the offcanvas title. Keep in mind that since we already add role="dialog" via JavaScript, developers don't need to add it.

CSS #

Variables #

Added in v1.0.1

As part of UX4G’s evolving CSS variables approach, offcanvas now uses local CSS variables on .offcanvas for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.

--#{$prefix}offcanvas-zindex: #{$zindex-offcanvas};
--#{$prefix}offcanvas-width: #{$offcanvas-horizontal-width};
--#{$prefix}offcanvas-height: #{$offcanvas-vertical-height};
--#{$prefix}offcanvas-padding-x: #{$offcanvas-padding-x};
--#{$prefix}offcanvas-padding-y: #{$offcanvas-padding-y};
--#{$prefix}offcanvas-color: #{$offcanvas-color};
--#{$prefix}offcanvas-bg: #{$offcanvas-bg-color};
--#{$prefix}offcanvas-border-width: #{$offcanvas-border-width};
--#{$prefix}offcanvas-border-color: #{$offcanvas-border-color};
--#{$prefix}offcanvas-box-shadow: #{$offcanvas-box-shadow};
--#{$prefix}offcanvas-transition: #{transform $offcanvas-transition-duration ease-in-out};
--#{$prefix}offcanvas-title-line-height: #{$offcanvas-title-line-height};

Sass variables #

$offcanvas-padding-y:               $modal-inner-padding;
$offcanvas-padding-x:               $modal-inner-padding;
$offcanvas-horizontal-width:        400px;
$offcanvas-vertical-height:         30vh;
$offcanvas-transition-duration:     .3s;
$offcanvas-border-color:            $modal-content-border-color;
$offcanvas-border-width:            $modal-content-border-width;
$offcanvas-title-line-height:       $modal-title-line-height;
$offcanvas-bg-color:                var(--#{$prefix}body-bg);
$offcanvas-color:                   var(--#{$prefix}body-color);
$offcanvas-box-shadow:              $modal-content-box-shadow-xs;
$offcanvas-backdrop-bg:             $modal-backdrop-bg;
$offcanvas-backdrop-opacity:        $modal-backdrop-opacity;

Usage #

The offcanvas plugin utilizes a few classes and attributes to handle the heavy lifting:

.offcanvas hides the content
.offcanvas.show shows the content
.offcanvas-start hides the offcanvas on the left
.offcanvas-end hides the offcanvas on the right
.offcanvas-top hides the offcanvas on the top
.offcanvas-bottom hides the offcanvas on the bottom

Add a dismiss button with the data-bs-dismiss="offcanvas" attribute, which triggers the JavaScript functionality. Be sure to use the <button> element with it for proper behavior across all devices.

Via data attributes #

Toggle #

To automatically allocate control of one offcanvas element, add the attributes data-bs-toggle="offcanvas" and a data-bs-target or href to the element. To apply the offcanvas to, the data-bs-target attribute accepts a CSS selector. Make sure the offcanvas element has the class offcanvas added. In order to open by default, add the extra class show.

Dismiss #

Dismissal can be achieved with the data attribute on a button within the offcanvas as demonstrated below:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" aria-label="Close"></button>

or on a button outside the offcanvas using the data-bs-target as demonstrated below:

<button type="button" class="btn-close" data-bs-dismiss="offcanvas" data-bs-target="#my-offcanvas" aria-label="Close"></button>

While both ways to dismiss an offcanvas are supported, keep in mind that dismissing from outside an offcanvas does not match the ARIA Authoring Practices Guide dialog (modal) pattern. Do this at your own risk.

Via JavaScript #

Enable manually with:

const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new UX4G.Offcanvas(offcanvasEl))

Options #

Data-bs-animation can have an option name appended to it, for example, data-bs-animation="value," since options can be provided through data attributes or JavaScript. When sending the choices via data attributes, be sure to modify the case type of the option name from "camelCase" to "kebab-case." Use data-bs-custom-class="beautifier" as opposed to data-bs-customClass="beautifier" for instance.

As of UX4G, every component supports the experimental reserved data property data-bs-config, which can store a JSON string for basic component setting. When an element has the data-bs-config='{"delay":0, "title":123}' and data-bs-title="456" attributes, the final title value will be 456 and the individual data attributes will take precedence over the values specified on the data-bs-config. Additionally, JSON variables like data-bs-delay='{"show":0,"hide":150}' can be stored in existing data attributes.

Name	Type	Default	Description
`backdrop`	boolean or the string `static`	`true`	Apply a backdrop on body while offcanvas is open. Alternatively, specify `static` for a backdrop which doesn’t close the offcanvas when clicked.
`keyboard`	boolean	`true`	Closes the offcanvas when escape key is pressed
`scroll`	boolean	`false`	Allow body scrolling while offcanvas is open

Methods #

Asynchronous methods and transitions

Every API method begins a transition and is asynchronous. When the transition begins, they call the caller back before it ends. A method call on a component that is transitioning will also be disregarded.

Activates your content as an offcanvas element. Accepts an optional options object.

You can create an offcanvas instance with the constructor, for example:

const bsOffcanvas = new UX4G.Offcanvas('#myOffcanvas')

Method	Description
`getInstance`	Static method which allows you to get the offcanvas instance associated with a DOM element
`getOrCreateInstance`	Static method which allows you to get the offcanvas instance associated with a DOM element, or create a new one in case it wasn’t initialized
`hide`	Hides an offcanvas element. Returns to the caller before the offcanvas element has actually been hidden (i.e. before the `hidden.bs.offcanvas` event occurs).
`show`	Shows an offcanvas element. Returns to the caller before the offcanvas element has actually been shown (i.e. before the `shown.bs.offcanvas` event occurs).
`toggle`	Toggles an offcanvas element to shown or hidden. Returns to the caller before the offcanvas element has actually been shown or hidden (i.e. before the `shown.bs.offcanvas` or `hidden.bs.offcanvas` event occurs).

Events #

UX4G’s offcanvas class exposes a few events for hooking into offcanvas functionality.

Method	Description
`getInstance`	Static method which allows you to get the offcanvas instance associated with a DOM element
`getOrCreateInstance`	Static method which allows you to get the offcanvas instance associated with a DOM element, or create a new one in case it wasn’t initialized
`hide`	Hides an offcanvas element. Returns to the caller before the offcanvas element has actually been hidden (i.e. before the `hidden.bs.offcanvas` event occurs).
`show`	Shows an offcanvas element. Returns to the caller before the offcanvas element has actually been shown (i.e. before the `shown.bs.offcanvas` event occurs).
`toggle`	Toggles an offcanvas element to shown or hidden. Returns to the caller before the offcanvas element has actually been shown or hidden (i.e. before the `shown.bs.offcanvas` or `hidden.bs.offcanvas` event occurs).

const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
  // do something...
})

How it works
Examples
- Offcanvas components
Live demo
Dark offcanvas
Body scrolling
Body scrolling and backdrop
Static backdrop
Responsive
Placement
Accessibility
CSS
- Variables
Sass variables
Usage
- Via data attributes
- Dismiss
Via JavaScript
Options
Methods
Events

Demo

Demo

Previous « Navs and Tabs

Next Pagination »

Offcanvas

How it works#

Examples

Offcanvas components#

Live demo#

RESULT

Offcanvas

Dark offcanvas #

Body scrolling #

RESULT

Offcanvas with body scrolling

Body scrolling and backdrop #

RESULT

Backdrop with scrolling

Static backdrop #

RESULT

Offcanvas

Responsive #

RESULT

Responsive offcanvas

Placement #

RESULT

Offcanvas top

RESULT

Offcanvas right

RESULT

Offcanvas bottom

Accessibility #

CSS #

Variables #

Sass variables #

Usage #

Via data attributes #

Toggle #

Dismiss #

Via JavaScript #

Options #

Methods #

Asynchronous methods and transitions ​

Events #

Accessibility options by UX4G

Asynchronous methods and transitions