timkelty / js-offcanvas

A lightweight, flexible jQuery off-canvas navigation plugin which lets you create fully accessible sidebar or top/bottom sliding (or push) panels with keyboard interactions and ARIA attributes.

js-offcanvas

jQuery accessible Offcanvas plugin, using ARIA

View Demo | Edit on Codepen

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 Bower: bower install js-offcanvas --save
• 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/dist/_js/js-offcanvas.pkgd.min.js"></script> 
<link href="https://unpkg.com/js-offcanvas/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

• Collection
• Codepen Template
• Demo Site Examples
• Full Width
• Codrops SVG Shape Overlays

Bootstrap v4

• Dashboard
• Starter
• Boxed Layout

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

http://offcanvas.vasilis.co

Dependencies

• jQuery
• Modernizr

---

License

Licensed under the MIT license.