# Off Canvas # Contextual sidebars positioned outside the viewport until activated. ## 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. ```html

... Primary content ...

``` Once we have our markup, the component can be initialized on the sidebars. ```javascript $('.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. ```javascript $('.off-canvas').offCanvas({ selector: '.js-open-sidebar' }); ``` Or we can toggle the display manually through the component instance. ```javascript $('#left-sidebar').toolkit('offCanvas', 'toggle'); ``` ### Multiple Sidebars ### Supporting left and right sidebars is extremely easy. Simply duplicate the markup and JavaScript for each side. ```html ``` 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. ```html ``` ### 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. ```javascript $('.off-canvas').offCanvas({ animation: 'reverse-push' }); ``` ### Open On Load ### Sidebars can be opened on page load by setting `openOnLoad` to true. ```javascript $('.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`. ## ARIA ## The `main` and `complementary` roles and the appropriate `aria-*` attributes are required when supporting ARIA. ```html

...

```

The JavaScript component will automatically map all ARIA attributes.

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

## Options ## Inherits all options from the [parent Component](component.md#options).

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.

## Events ## Inherits all events from the [parent Component](component.md#events).

Event	Arguments	Description
resize		Triggered when the browser is resized.

## Properties ## Inherits all properties from the [parent Component](component.md#properties).

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.

## Methods ## Inherits all methods from the [parent Component](component.md#methods).

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