rooty/Bootstrap
0
0
Fork 0
mirror of https://github.com/twbs/bootstrap.git synced 2024-12-03 15:24:19 +01:00
Code Issues Actions Packages Releases Activity
a49d1e3e58
Bootstrap/site/content/docs/5.0/components/offcanvas.md
GeoSot 548be2ed66
Offcanvas as component (#29017) 
* Add a new offcanvas component

* offcanvas.js: switch to string constants and `event.key`

* Remove unneeded code

* Sass optimizations

* Fixes

Make sure the element is hidden and not offscreen when inactive
fix close icon negative margins
Add content in right & bottom examples
Re-fix bottom offcanvas height not to cover all viewport

* Wording tweaks

* update tests and offcanvas class

* separate scrollbar functionality and use it in offcanvas

* Update .bundlewatch.config.json

* fix focus

* update btn-close / fix focus on close

* add aria-modal and role
return focus on trigger when offcanvas is closed
change body scrolling timings

* move common code to reusable functions

* add aria-labelledby

* Replace lorem ipsum text

* fix focus when offcanvas is closed

* updates

* revert modal, add tests for scrollbar

* show backdrop by default

* Update offcanvas.md

* Update offcanvas CSS to better match modals

- Add background-clip for borders
- Move from outline to border (less clever, more consistent)
- Add scss-docs in vars

* Revamp offcanvas docs

- Add static example to show and explain the components
- Split live examples and rename them
- Simplify example content
- Expand docs notes elsewhere
- Add sass docs

* Add .offcanvas-title instead of .modal-title

* Rename offcanvas example to offcanvas-navbar to reflect it's purpose

* labelledby references title and not header

* Add default shadow to offcanvas

* enable offcanvas-body to fill all the remaining wrapper area

* Be more descriptive, on Accessibility area

* remove redundant classes

* ensure in case of an already open offcanvas, not to open another one

* bring back backdrop|scroll combinations

* bring back toggling class

* refactor scrollbar method, plus tests

* add check if element is not full-width, according to #30621

* revert all in modal

* use documentElement innerWidth

* Rename classes to -start and -end

Also copyedit some docs wording

* omit some things on scrollbar

* PASS BrowserStack tests

-- IOS devices, Android devices and Browsers on Mac, hide scrollbar by default and appear it, only while scrolling.

* Rename '_handleClosing' to '_addEventListeners'

* change pipe usage to comma

* change Data.getData to Data.get

Co-authored-by: XhmikosR <xhmikosr@gmail.com>
Co-authored-by: Martijn Cuppens <martijn.cuppens@gmail.com>
Co-authored-by: Mark Otto <markdotto@gmail.com>
2021-03-02 19:10:10 +02:00

12 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, 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 "callout-info-prefersreducedmotion.md" >}} {{< /callout >}}

Examples

Offcanvas components

Below is a static offcanvas example (meaning its position, display, and visibility have been overridden). 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-light" >}}

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

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-bottom places offcanvas on the bottom of the viewport

Try the right and bottom examples out below.

{{< example >}} Toggle right offcanvas

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

{{< example >}} Toggle bottom offcanvas

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

Options

By default, we disable scrolling on the <body> when an offcanvas is visible and use a gray backdrop. Use the data-bs-body attribute to enable <body> scrolling, or a combination of both options

{{< example >}} Enable body scrolling Enable backdrop (default) Enable both scrolling & backdrop

Colored with scrolling

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

Offcanvas with backdrop

.....

Backdroped with scrolling

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

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

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-bottom hides the offcanvas on the bottom
  • data-bs-body="scroll" enables <body> scrolling when offcanvas is open
  • data-bs-body="backdrop" disables scrolling and creates a backdrop over the <body> when offcanvas is open (default)
  • data-bs-body="backdrop,scroll" combines both options to enable <body> scrolling and create a backdrop over the <body> when offcanvas is open

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

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.

Via JavaScript

Enable manually with:

var offcanvasElementList = [].slice.call(document.querySelectorAll('.offcanvas'))
var offcanvasList = offcanvasElementList.map(function (offcanvasEl) {
  return new bootstrap.Offcanvas(offcanvasEl)
})

Methods

{{< callout danger >}} {{< partial "callout-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:

var myOffcanvas = document.getElementById('myOffcanvas')
var bsOffcanvas = new bootstrap.Offcanvas(myOffcanvas)
Method Description
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).
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).
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).
_getInstance Static method which allows you to get the offcanvas instance associated with a DOM element

Events

Bootstrap's offcanvas class exposes a few events for hooking into offcanvas functionality.

Event Type Description
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).
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). 
var myOffcanvas = document.getElementById('myOffcanvas')
myOffcanvas.addEventListener('hidden.bs.offcanvas', function () {
  // do something...
})