rooty/Bootstrap
0
0
Fork 0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-12 00:08:59 +01:00
Code Issues Actions Packages Releases Activity
41f62c5a11
Bootstrap/site/content/docs/5.2/components/offcanvas.md
Mark Otto fc3f4b67d6
Add dark mode support (#35857) 
* Add dark mode to docs

* Minor fix: missing space indentation

* Minor fix: revert utilities/z-index added-in modification

* Remove prev: and next: from doc because extracted to another PR

* Use .bg-body-tertiary in all Utilities > Overflow examples

* fix example

* Fix up spacing examples

* Update box-shadow Sass variables and utilities to auto-adjust to color modes

* Remove unused docs class

* Refactor form styles to use CSS variable for background images on .form-check and .form-switch

* Fix docs selector

* Rename shortcut for clarity

* Heading consistency

* Reintroduce missing 4th grid item in Utilities > Spacing example

* Fix bundlewatch

* .bd-callout* rendering is OK so removing comments in the code

* Update scss/_utilities.scss

Co-authored-by: Julien Déramond <julien.deramond@orange.com>

* Fix gutters example styling

* Fix text colors on background utils docs

* redesign and fix up position marker example, which doesn't show nicely in darkmode but at least isn't broken

* fix some color utils examples

* Deprecate mixin notice

* Deprecate notice for list-group-item-variant() mixin

* Revamp new link CSS vars

* Use map-keys in some each Sass files

* Remove list-group-item-variant mixin ref in sass loop desc

* Display CSS vars scoped to our built-in dark mode

* Revert previous commit

* Fix list group variant link

* Fix typo

* Remove imports of alert/list-group mixins in scss/_mixins.scss

* Small formatting + comments removal in scss/_content.scss

* Fix alert links colors

* fix dropdown border-radius mixin

* fix link color and underline again, this time using CSS var override for color var and fallback value for the underline

* fix colors on docs navbar for dark mode

* remove two changes

* missing ref

* another link underline fix, just use sass vars for link decoration for now

* missing color bg docs, plus move dropdown override to scss

* more changes from review

* fix some examples, drop unused docs navbar styles, update docs navbar color mode to use mixin

* Few fixes around type

- Restored CSS variable for color on headings, this time with a fallback value
- In conjunction, restored and wrapped the default CSS var with a null value check
- Split headings and paragraphs docs in Reboot, elaborated on them

* Restyle custom details > summary element in docs

* Rewrite some migration docs

* fix form checks

* Fix up some navbar styling, tweak docs callout

* Fix select images, mostly for validation styling

* Clean up some migration notes, document some new form control CSS vars, mention new variables-dark in sass docs

* Update site/content/docs/5.2/components/scrollspy.md

Co-authored-by: Julien Déramond <julien.deramond@orange.com>

* Apply suggestions from code review

Co-authored-by: Julien Déramond <julien.deramond@orange.com>

* mention form control css vars in migration guide

* Tweak grid and flex docs background examples

* clarify some docs

* fix some more things

Co-authored-by: Julien Déramond <juderamond@gmail.com>
Co-authored-by: Julien Déramond <julien.deramond@orange.com>
2022-11-28 22:30:26 -08:00

16 KiB
Raw Blame History

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
Content for the offcanvas goes here. You can place just about any Bootstrap component or custom elements here.
{{< /example >}}

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
Some text as placeholder. In real life you can have the elements you have chosen. Like, text, images, lists, etc.
{{< /example >}}

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.

{{< /example >}}

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.

{{< /example >}}

Static backdrop

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

{{< example >}} Toggle static offcanvas

Offcanvas
I will not close if you click outside of me.
{{< /example >}}

Dark offcanvas

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

{{< example class="bd-example-offcanvas p-0 bg-body-secondary overflow-hidden" >}}

Offcanvas

Place offcanvas content here.

{{< /example >}}

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

Resize your browser to show the responsive offcanvas toggle.
Responsive offcanvas

This is content within an .offcanvas-lg.

{{< /example >}}

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

{{< example >}} Toggle right offcanvas

Offcanvas right
...
{{< /example >}}

{{< example >}} Toggle bottom offcanvas

Offcanvas bottom
...
{{< /example >}}

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