16 KiB
layout | title | description | group | toc |
---|---|---|---|---|
docs | Offcanvas | Build hidden sidebars into your project for navigation, shopping carts, and more with a few classes and our JavaScript plugin. | components | true |
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.
- Offcanvas shares some of the same JavaScript code as modals. Conceptually, they are quite similar, but they are separate plugins.
- Similarly, some source Sass variables for offcanvas's styles and dimensions are inherited from the modal's variables.
- When shown, offcanvas includes a default backdrop that can be clicked to hide the offcanvas.
- Similar to modals, only one offcanvas can be shown at a time.
Heads up! Given how CSS handles animations, you cannot use margin
or translate
on an .offcanvas
element. Instead, use the class as an independent wrapping element.
{{< callout info >}} {{< partial "callouts/info-prefersreducedmotion.md" >}} {{< /callout >}}
Examples
Offcanvas components
Below is an offcanvas example that is shown by default (via .show
on .offcanvas
). Offcanvas includes support for a header with a close button and an optional body class for some initial padding
. We suggest that you include offcanvas headers with dismiss actions whenever possible, or provide an explicit dismiss action.
{{< example class="bd-example-offcanvas p-0 bg-body-tertiary overflow-hidden" >}}
Offcanvas
Live demo
Use the buttons below to show and hide an offcanvas element via JavaScript that toggles the .show
class on an element with the .offcanvas
class.
.offcanvas
hides content (default).offcanvas.show
shows content
You can use a link with the href
attribute, or a button with the data-bs-target
attribute. In both cases, the data-bs-toggle="offcanvas"
is required.
{{< example >}} Link with href Button with data-bs-target
Offcanvas
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.
{{< example >}} Enable body scrolling
Offcanvas with body scrolling
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.
{{< example >}} Enable both scrolling & backdrop
Backdrop with scrolling
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.
{{< example >}} Toggle static offcanvas
Offcanvas
Dark offcanvas
{{< deprecated-in "5.3.0" >}} {{< added-in "5.2.0" >}}
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
.
{{< callout warning >}}
Heads up! Dark variants for components were deprecated in v5.3.0 with the introduction of color modes. Instead of manually adding classes mentioned above, set data-bs-theme="dark"
on the root element, a parent wrapper, or the component itself.
{{< /callout >}}
{{< example class="bd-example-offcanvas p-0 bg-body-secondary overflow-hidden" >}}
Offcanvas
Place offcanvas content here.
Responsive
{{< added-in "5.2.0" >}}
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.
{{< example >}} Toggle offcanvas
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
There's no default placement for offcanvas components, so you must add one of the modifier classes below.
.offcanvas-start
places offcanvas on the left of the viewport (shown above).offcanvas-end
places offcanvas on the right of the viewport.offcanvas-top
places offcanvas on the top of the viewport.offcanvas-bottom
places offcanvas on the bottom of the viewport
Try the top, right, and bottom examples out below.
{{< example >}} Toggle top offcanvas
Offcanvas top
{{< example >}} Toggle right offcanvas
Offcanvas right
{{< example >}} Toggle bottom offcanvas
Offcanvas bottom
Accessibility
Since the offcanvas panel is conceptually a modal dialog, be sure to add aria-labelledby="..."
—referencing the offcanvas title—to .offcanvas
. Note that you don’t need to add role="dialog"
since we already add it via JavaScript.
CSS
Variables
{{< added-in "5.2.0" >}}
As part of Bootstrap'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.
{{< scss-docs name="offcanvas-css-vars" file="scss/_offcanvas.scss" >}}
Sass variables
{{< scss-docs name="offcanvas-variables" file="scss/_variables.scss" >}}
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
Add data-bs-toggle="offcanvas"
and a data-bs-target
or href
to the element to automatically assign control of one offcanvas element. The data-bs-target
attribute accepts a CSS selector to apply the offcanvas to. Be sure to add the class offcanvas
to the offcanvas element. If you'd like it to default open, add the additional class show
.
Dismiss
{{% js-dismiss "offcanvas" %}}
{{< callout warning >}} 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. {{< /callout >}}
Via JavaScript
Enable manually with:
const offcanvasElementList = document.querySelectorAll('.offcanvas')
const offcanvasList = [...offcanvasElementList].map(offcanvasEl => new bootstrap.Offcanvas(offcanvasEl))
Options
{{< markdown >}} {{< partial "js-data-attributes.md" >}} {{< /markdown >}}
{{< bs-table "table" >}}
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. |
{{< /bs-table >}} |
Methods
{{< callout danger >}} {{< partial "callouts/danger-async-methods.md" >}} {{< /callout >}}
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 bootstrap.Offcanvas('#myOffcanvas')
{{< bs-table "table" >}}
Method | Description |
---|---|
dispose |
Destroys an element's offcanvas. |
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). |
{{< /bs-table >}} |
Events
Bootstrap's offcanvas class exposes a few events for hooking into offcanvas functionality.
{{< bs-table "table" >}}
Event type | Description |
---|---|
hide.bs.offcanvas |
This event is fired immediately when the hide method has been called. |
hidden.bs.offcanvas |
This event is fired when an offcanvas element has been hidden from the user (will wait for CSS transitions to complete). |
hidePrevented.bs.offcanvas |
This event is fired when the offcanvas is shown, its backdrop is static and a click outside of the offcanvas is performed. The event is also fired when the escape key is pressed and the keyboard option is set to false . |
show.bs.offcanvas |
This event fires immediately when the show instance method is called. |
shown.bs.offcanvas |
This event is fired when an offcanvas element has been made visible to the user (will wait for CSS transitions to complete). |
{{< /bs-table >}} |
const myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', event => {
// do something...
})