js-offcanvas

jQuery Accesible Offcanvas Panels

Usage no npm install needed!

<script type="module">
  import jsOffcanvas from 'https://cdn.skypack.dev/js-offcanvas';
</script>

README

js-offcanvas

Downloads Version AMA

jQuery accessible Offcanvas plugin, using ARIA

Demo

Why it is accessible

  • It relies on ARIA Design pattern for Dialogs
  • The tab key loops through all of the keyboard focusable items within the offcanvas
  • You can close it using Esc.

Features

  • Uses CSS transforms & transitions.
  • BEM c-offcanvas c-offcanvas--left is-open
  • From Any Direction: left, right, top and bottom.
  • Overlay, Reveal and Push.
  • API & Events
  • Package managers Bower & NPM

Getting Started

  • Install with npm: npm install js-offcanvas
  • Install with yarn: yarn add js-offcanvas
JS & CSS

Include the .css and .js files in your site.

<script src="js-offcanvas.pkgd.min.js"></script>
<link href="js-offcanvas.css" rel="stylesheet">
CDN
<script src="https://unpkg.com/js-offcanvas@1.2.8/dist/_js/js-offcanvas.pkgd.min.js"></script> 
<link href="https://unpkg.com/js-offcanvas@1.2.8/dist/_css/prefixed/js-offcanvas.css" rel="stylesheet">
HTML

Offcanvas works on a container element with no styles applied.

    <div class="c-offcanvas-content-wrap">
        <a href="#offCanvas" id="triggerButton">Menu</a>
         <!-- Your Main Content goes here -->
    </div>
    
    <aside id="offCanvas"></aside>
Initialize

$('#offCanvas').offcanvas({
    modifiers: 'left, overlay', // default options
    triggerButton: '#triggerButton' // btn to open offcanvas
});
Initialize with HTML
Trigger Button

Include the CSS-Class js-offcanvas-trigger and data-offcanvas-trigger="id-of-your-offcanvas"

<a  class="js-offcanvas-trigger" 
    data-offcanvas-trigger="off-canvas-id"
    href="#off-canvas">Menu</a>
Offcanvas Element

Include the CSS-Class js-offcanvas and data-offcanvas-options="{options}"

<aside class="js-offcanvas" 
       data-offcanvas-options='{"modifiers": "left,overlay"}' 
       id="off-canvas-id">...</aside>
Trigger Enhance
  // you have to trigger enhance
   $( function(){
       $(document).trigger("enhance");
   });

Options

$('#offCanvas').offcanvas({    
    role: "dialog",
    modifiers: "left,overlay",
    baseClass: "c-offcanvas",
    modalClass: "c-offcanvas-bg",
    contentClass: "c-offcanvas-content-wrap",
    closeButtonClass: "js-offcanvas-close",
    bodyModifierClass: "has-offcanvas",
    supportNoTransitionsClass: "support-no-transitions",
    resize: false,
    triggerButton: '#triggerButton' ,
    modal: true,
    onOpen: function() {},
    onClose: function() {},
    onInit: function() {}
})
.on( "create.offcanvas", function( e ){ } )
.on( "open.offcanvas", function( e ){ } )
.on( "opening.offcanvas", function( e ){ } )
.on( "close.offcanvas", function( e ){ } )
.on( "closing.offcanvas", function( e ){ } )
.on( "resizing.offcanvas", function( e ){ } );

Examples on Codepen

Bootstrap v4

Options

Set instance options by passing a valid object at initialization, or to the public defaults method. Custom options for a specific instance can also be set by attaching a data-offcanvas-options attribute to the target elment. This attribute should contain the properly formatted JSON object representing the custom options.

 data-offcanvas-options='{ "modifiers": "left,overlay",... }'
Name Default Type
modifiers "left,overlay" string
baseClass "c-offcanvas" string
modalClass "c-offcanvas-bg" string
contentClass "c-offcanvas-content-wrap" string
closeButtonClass "js-offcanvas-close" string
role "dialog" string
bodyModifierClass "has-offcanvas" string
supportNoTransitionsClass "support-no-transitions" string
resize false boolean
triggerButton null string
onInit null function
onOpen null function
onClose null function

API

The offcanvas API offers a couple of methods to control the offcanvas and are publicly available to all active instances.

var dataOffcanvas = $('#off-canvas').data('offcanvas-component');

Methods

open

dataOffcanvas.open();

close

dataOffcanvas.close();

toggle

dataOffcanvas.toggle();

Callbacks

onInit

Fires an event when offcanvas is initialized.

dataOffcanvas.onInit = function() {
    console.log(this);
};

onOpen

Fires an event when offcanvas is opened.

dataOffcanvas.onOpen = function() {
    console.log('Callback onOpen');
};

onClose

Fires an event when offcanvas is closed.

dataOffcanvas.onClose  = function() {
    console.log(this);
};

Events

jQuery.offcanvas fires several events. Simply listen for them with the jQuery.on function. All events are namespaced with offcanvas.

beforecreate

Fires an event before the offcanvas is initialized.

$( document ).on( "beforecreate.offcanvas", function( e ){
    var dataOffcanvas = $( e.target ).data('offcanvas-component');
    console.log(dataOffcanvas);
    dataOffcanvas.onInit =  function() {
        console.log(this);
    };
} );

create

Fired once the Plugin is initialized.

$( document ).on( "create.offcanvas", function( e ){ } );

open

Fired when the open method is called.

$( document ).on( "open.offcanvas", function( e ){ } );

close

Fired when the close method is called.

$( document ).on( "close.offcanvas", function( e ){ } );

resizing

Fired when the window is resized.

$( document ).on( "resizing.offcanvas", function( e ){ } );

clicked

Fired when the trigger-btn is clicked.

$( document ).on( "clicked.offcanvas-trigger", function( e ){
    var dataBtnText = $( e.target ).text();
    console.log(e.type + '.' + e.namespace + ': ' + dataBtnText);
} );

Dependencies

  • jQuery

License

Licensed under the MIT license.