1. Docs
  2. Offcanvas

Offcanvas Component

Implement and customize the Offcanvas component for sliding panels and sidebars.

UnoCSS PresetTailwind Plugin
The Offcanvas component allows you to create a sliding panel that appears from the side of the screen, commonly used for navigation menus or sidebars. This component is fully customizable, supporting backdrop visibility, body scroll control, and various lifecycle hooks for more control over its behavior.

Installation

To use the Offcanvas component, you can install it via npm:

Structure

Markup Structure

  • offcanvas-trigger: Element that triggers the Offcanvas, with data-offcanvas-trigger and data-target attributes, the value of data-target must be the targeted offcanvas.
  • offcanvas-element: The offcanvas element, must have an id
  • close-offcanvas-elements: any element inside the offcanvas-element with data-offcanvas-close attribute
Here is a basic example of how to structure your offcanvas/SliderOver and trigger elements in HTML: 
<!-- Trigger Button -->
<button data-offcanvas-target="myOffcanvas" aria-haspopup="dialog">Open Offcanvas</button>
<!-- Offcanvas Panel -->
<div id="myOffcanvas" role="dialog" aria-hidden="true" class="offcanvas" >
  <button class="offcanvas-close-btn" aria-label="Close Offcanvas">X</button>
  <p>This is the offcanvas content!</p>
</div>
  • Adding a overlay element 
<div id="myOffcanvas" role="dialog" aria-hidden="true" class="offcanvas" data-offcanvas-backdrop="your backdrop classes"></div>

Example

Offcanvas Options

The Offcanvas component can be customized using the OffcanvasOptions object, which provides control over backdrop visibility, body scroll behavior, and event hooks.

staticBackdrop

Prevents the offcanvas from being closed by clicking the backdrop. Useful for alert or confirmation-type offcanvas components.
  • Type: boolean
  • Default: false

allowBodyScroll

Allows the body to scroll while the offcanvas is open. Set this to false to lock body scrolling.
  • Type: boolean
  • Default: false

backdrop

Setting the backdrop classes

Example:

beforeHide

A function that executes right before the offcanvas is hidden. Returning { cancelAction: true } will prevent the offcanvas from closing.
  • Type: () => { cancelAction?: boolean; } | void

beforeShow

A function that executes before the offcanvas is shown.
  • Type: () => void

onShow

A callback function that triggers when the offcanvas is shown.
  • Type: () => void

onHide

A callback function that triggers when the offcanvas is hidden.
  • Type: () => void

Initialization Example

Here’s an example of initializing an offcanvas with custom options: 
import { OffCanvas } from '@flexilla/offcanvas';

const offcanvas = new OffCanvas('#myOffcanvas', {
  staticBackdrop: true,
  allowBodyScroll: false,
  backdrop: 'custom-backdrop-class',
  beforeHide() {
    console.log('Before offcanvas hides');
    return { cancelAction: false }; // You can cancel hide by setting cancelAction to true
  },
  beforeShow() {
    console.log('Before offcanvas shows');
  },
  onShow() {
    console.log('Offcanvas is shown');
  },
  onHide() {
    console.log('Offcanvas is hidden');
  }
});

Methods

open()

Programmatically opens the offcanvas. 
offcanvas.open();

close()

Programmatically closes the offcanvas. 
offcanvas.close();

setOptions()

Update supported runtime options after initialization. 
offcanvas.setOptions({
  allowBodyScroll: true,
});

cleanup()

Remove the event listeners attached by the component when the instance is no longer needed. 
offcanvas.cleanup();

autoInit()

Initialize all matching offcanvas elements. By default, OffCanvas.autoInit() looks for [data-fx-offcanvas]. 
import { OffCanvas } from "@flexilla/offcanvas";

OffCanvas.autoInit();
// or
OffCanvas.autoInit(".my-offcanvas");

Events

The offcanvas element dispatches custom events you can listen to in your app logic.

offcanvas-before-hide

Fires right before the offcanvas closes.

offcanvas-open

Fires when the offcanvas is opened.

offcanvas-close

Fires when the offcanvas is closed. 
const offcanvasEl = document.querySelector("#myOffcanvas");
const offcanvas = new OffCanvas(offcanvasEl);

offcanvasEl.addEventListener("offcanvas-open", (event) => {
  console.log("Opened", event.detail.offcanvasId);
});

offcanvasEl.addEventListener("offcanvas-before-hide", (event) => {
  const shouldPreventClose = false;

  if (shouldPreventClose) {
    event.detail.setExitAction(true);
  }
});
You can also trigger open and close actions through document events when the component is initialized: 
document.dispatchEvent(new Event("sheet:myOffcanvas:open"));
document.dispatchEvent(new Event("sheet:myOffcanvas:close"));