Top

Usage

Off canvas provides a mechanism for positioning contextual sidebars outside of the viewport (on the left or right), which can then be slid into view when activated. Supporting off canvas sidebars is relatively easy.

The first thing we need to do is place a .canvas wrapper within the body, and within that an .on-canvas element where all site content should reside. Lastly, we place the .off-canvas sidebars within the wrapper.

<body>
    <div class="canvas" data-offcanvas>
        <main class="on-canvas" data-offcanvas-content>
            ... Primary content ...
        </main>

        <aside class="off-canvas off-canvas--left" id="left-sidebar" data-offcanvas-sidebar="left">
            ... Sidebar content ...
        </aside>
    </div>
</body>

Once we have our markup, the component can be initialized on the sidebars.

$('.off-canvas').offCanvas();
The data-offcanvas-* attributes are required so that the JavaScript layer can find or bind elements in the DOM.
The data-offcanvas-sidebar attribute must be set to either "left" or "right".
Mobile specific sidebars are supported through CSS media queries and Sass variables.

Toggle Sidebars

When initializing a component, a selector option can be defined that will be bound with click toggle events.

$('.off-canvas').offCanvas({
    selector: '.js-open-sidebar'
});

Or we can toggle the display manually through the component instance.

$('#left-sidebar').toolkit('offCanvas', 'toggle');

Multiple Sidebars

Supporting left and right sidebars is extremely easy. Simply duplicate the markup and JavaScript for each side.

<aside class="off-canvas off-canvas--left" id="left-sidebar" data-offcanvas-sidebar="left">...</aside>
<aside class="off-canvas off-canvas--right" id="right-sidebar" data-offcanvas-sidebar="right">...</aside>

The component also supports multiple sidebars on the same side. However, be weary of this approach and the animations being used as it might run into weirdness.

<aside class="off-canvas off-canvas--left" id="primary-sidebar" data-offcanvas-sidebar="left">...</aside>
<aside class="off-canvas off-canvas--left" id="secondary-sidebar" data-offcanvas-sidebar="left">...</aside>

Animations

There are 7 types of animations that can be used for displaying a sidebar, each with their own unique presentation.

  • push - Pushes the content off the screen to make room for the sidebar.
  • push-reveal - A combination of the push and reveal animation.
  • push-down - Pushes the content off the screen while the sidebar slides down from above.
  • reverse-push - Similar to the push animation, but the sidebar slides in from the opposite side.
  • reveal - The content slides off the screen to reveal the sidebar beneath it.
  • squish - The content stays on screen, but is squished via padding to make room for the sidebar.
  • on-top - The sidebar slides over the content.
$('.off-canvas').offCanvas({
    animation: 'reverse-push'
});

Open On Load

Sidebars can be opened on page load by setting openOnLoad to true.

$('.off-canvas').offCanvas({
    openOnLoad: true
});
We suggest using this with the on-top or squish animations.

Notes

  • When a sidebar is open, an .is-expanded class will be added to the sidebar.
  • When a sidebar is open, a .move-left or .move-right class will be added to the .canvas.
Top

ARIA

The main and complementary roles and the appropriate aria-* attributes are required when supporting ARIA.

<main class="on-canvas" role="main" data-offcanvas-content>
    ...
</main>

<aside class="off-canvas off-canvas--left" role="complementary" data-offcanvas-sidebar="left">
    ...
</aside>
The JavaScript component will automatically map all ARIA attributes.
Top

Variables

Variable Default Description
$offCanvas-animations ("push", "push-reveal", "push-down", "reverse-push", "reveal", "on-top", "squish") A list of all animations to include in the CSS output.
$offCanvas-class .off-canvas CSS class name for the off canvas sidebar.
$offCanvas-class-content .on-canvas CSS class name for the off canvas primary content wrapper.
$offCanvas-class-wrapper .canvas CSS class name for the off canvas parent wrapper.
$offCanvas-class-modifier-left .off-canvas--left CSS class name for the off canvas left modifier.
$offCanvas-class-modifier-right .off-canvas--right CSS class name for the off canvas right modifier.
$offCanvas-left-width 20% The width of the left sidebar.
$offCanvas-left-width-mobile 90% The width of the left sidebar for mobile devices.
$offCanvas-mobile-breakpoint 640px The break point to apply mobile widths.
$offCanvas-right-width 20% The width of the right sidebar.
$offCanvas-right-width-mobile 90% The width of the right sidebar for mobile devices.
$offCanvas-transition .5s The transition time for sidebar slide animations.
$offCanvas-zindex 250 The z-index for the sidebar element.
Top

Options

Inherits all options from the parent Component.

Option Type Default Description
animation string push Animation to use when displaying the sidebar. Accepts push, push-reveal, push-down, reverse-push, reveal, squish, on-top.
hideOthers bool true Will hide all other sidebars when opening a sidebar.
openOnLoad bool false Will automatically display the sidebar on page load. Transitions will not be triggered during this.
selector string CSS selector to bind click toggle events to.
stopScroll bool true Whether to remove the scrollbar on the window while the sidebar is open. Requires html.touch for mobile devices to function properly.
swipe bool Toolkit.isTouch Will bind swipe events. If this is true on non-touch devices, it will bind equivalent mouse events.
Top

Events

Inherits all events from the parent Component.

Event Arguments Description
resize Triggered when the browser is resized.
Top

Properties

Inherits all properties from the parent Component.

Property Type Description Found With
container element The parent element that contains the sidebar. parent
opposite string The opposite of side.
primary element The primary element that contains the content. [data-offcanvas-content]
secondary element The other sidebars within the canvas. [data-offcanvas-sidebar]
side string The side where the sidebar is positioned. Will either be left or right.
Top

Methods

Inherits all methods from the parent Component.

Method Description Bound To
toggle() Toggle the display of the sidebar. selector option