Stackable Offcanvas Panel Plugin for Bootstrap 5 - jQuery bs-layer

bs-layer is a sliding layer plugin for jQuery and Bootstrap 5 that enables an offcanvas sidebar drawer sliding out from the side of the screen. 

It's designed to help you create animated, stackable panels/modals perfect for navigation menus, settings panels, user profiles, and multi-level content displays.

Features

• Stackable layers: Open multiple panels simultaneously with automatic positioning.
• AJAX content loading: Load dynamic content from URLs or custom functions.
• Smooth animations: Configurable slide transitions with proper timing.
• Bootstrap 5 based: Uses Bootstrap's utility classes and design patterns.
• Keyboard support: ESC key closes layers, full accessibility compliance.
• Responsive design: Adapts to different screen sizes with breakpoint handling.
• Custom events: Callback system for all layer states.
• Backdrop control: Static or dismissible backdrop options.

How to use it:

1. Load the necessary jQuery library, Bootstrap 5 framework, and Bootstrap Icons in your project.

<!-- jQuery -->
<script src="/path/to/cdn/jquery.min.js"></script>

<!-- Bootstrap -->
<link rel="stylesheet" href="/path/to/cdn/bootstrap.min.css" />
<script src="/path/to/cdn/bootstrap.bundle.min.js"></script>

<!-- Bootstrap Icons -->
<link rel="stylesheet" href="/path/to/cdn/bootstrap-icons.min.css">

2. Load the bs-layer.js script after jQuery and Bootstrap.

<script src="dist/bs-layer.min.js"></script>

3. Create an anchor or button element that will act as the trigger for opening a layer. The data-url attribute is a quick way to specify the content source.

<a id="trigger" data-url="external.html" href="#">
  Open Layer
</a>

4. Initialize the plugin. That's it.

const instance = $('#trigger').bsLayer({
  // options here
});

5. Available options and callbacks to customize the layer.

• name: A unique string to identify the layer, which is necessary for targeting it with custom events.
• title: The text or HTML for the layer's header.
• width: The layer's width in pixels or as a CSS string (e.g., '50%'). This applies on viewports wider than the fullWidthBreakpoint.
• bgStyle: An object to customize the layer's background styling, containing classes (CSS classes) and css (inline style properties).
• backdrop: Determines the backdrop behavior. Use true to show a backdrop that closes the layer on click, false for no backdrop, or 'static' for a backdrop that doesn't close the layer.
• url: The source for the layer's content. This can be a URL for an AJAX request or a function that returns a Promise, which resolves with the HTML content.
• refreshable: A boolean (true/false) to show or hide the content refresh button in the header.
• closeable: A boolean to control the visibility of the close (X) button.
• expandable: A boolean to show or hide the maximize/minimize button.
• queryParams: A function that can modify the parameters sent with an AJAX request. It receives a params object and should return the modified object.
• onAll: A callback function that fires for every event triggered on the layer.
• onPostBody: A callback that executes after the layer's content has been successfully loaded and injected into the DOM.
• onShow: A callback that fires just before the layer begins to animate into view.
• onShown: A callback that fires after the layer's show animation has completed.
• onHide: A callback that fires just before the layer begins to animate out of view.
• onHidden: A callback that fires after the layer is fully hidden and removed from the DOM.
• onRefresh: A callback that executes when the layer's content is refreshed.
• onCustomEvent: A callback to handle custom events sent to the layer via $.bsLayer.customEvent().

const instance = $('#trigger').bsLayer({
  ajax: {
    method: 'GET',
    contentType: 'application/x-www-form-urlencoded; charset=UTF-8'
  },
  name: undefined,
  title: undefined,
  width: undefined,
  bgStyle: {
    classes: 'text-dark',
    css: {
      background: 'rgba(255, 255, 255, 0.74)',
      boxShadow: '0 16px 80px rgba(0, 0, 0, 0.7)',
      backdropFilter: 'blur(9.1px)',
      WebkitBackdropFilter: 'blur(9.1px)',
    }
  },
  backdrop: true,
  url: undefined,
  refreshable: false,
  closeable: true,
  expandable: true,
  queryParams(params) {
    return params;
  },
  onAll: function (_eventName, ..._args) {
  },
  onPostBody: function (_$content) {
  },
  onShow: function () {
  },
  onShown: function () {
  },
  onHide: function () {
  },
  onHidden: function () {
  },
  onRefresh: function (_$content) {
  },
  onCustomEvent: function (_eventName, ...params) {
  },
});

6. Here are the global configuration options for bs-layer. These settings are defined in the $.bsLayer.config object and apply to all layers unless an individual layer overrides them. You can modify them using $.bsLayer.setConfig().

• ajax.method: The default HTTP method (e.g., 'GET' or 'POST') used for all AJAX requests.
• ajax.contentType: The Content-Type header sent with AJAX requests.
• fullWidthBreakpoint: The viewport width in pixels (default: 576) below which all layers will automatically expand to 100% width.
• firstLayerWithInPercent: The width of the first opened layer, expressed as a percentage of the window width (e.g., 0.8 for 80%).
• distanceBetweenLayers: The offset in pixels that each subsequent layer is shifted to the left from the previous one, creating the stacked appearance.
• animationDuration: The base duration in milliseconds for the slide-in and slide-out animations.
• zIndexStart: The initial z-index value for the very first layer. Each new layer gets a higher z-index.
• parent: The CSS selector for the DOM element into which all layer elements will be appended. Defaults to 'body'.
• icons.close: The CSS class(es) for the close (X) icon in the header.
• icons.refresh: The CSS class(es) for the refresh icon.
• icons.maximize: The CSS class(es) for the maximize icon.
• icons.minimize: The CSS class(es) for the minimize icon.
• onError: A global callback function that is triggered whenever a layer or AJAX error occurs.

$.bsLayer.setConfig({
  debug: true,
  ajax: {
    method: 'GET',
    contentType: 'application/x-www-form-urlencoded; charset=UTF-8'
  },
  fullWidthBreakpoint: 576, 
  firstLayerWithInPercent: .80,
  distanceBetweenLayers: 100, 
  animationDuration: 600, 
  zIndexStart: 1050, 
  parent: 'body',
  icons: {
    close: 'bi bi-x-lg',
    refresh: 'bi bi-arrow-clockwise',
    maximize: 'bi bi-arrows-angle-expand',
    minimize: 'bi bi-arrows-angle-contract', 
  }
});

7. Dynamic Content with Promises. You can use a function that returns a Promise instead of a static URL:

$('#trigger').bsLayer({
  name: 'dynamic-layer',
  url: async function(params) {
    const response = await fetch(`/api/content?id=${params.id}`);
    const html = await response.text();
    return html;
  },
  queryParams: (params) => {
    params.id = 123;
    return params;
  }
});

8. API methods.

• setTitle(title): Dynamically updates the header title of the layer. The title can be a plain string or HTML.
• show(): Programmatically opens the layer, simulating a click on its trigger element.
• refresh(): Reloads the layer's content. This is useful for layers with dynamic data that needs to be updated without closing and reopening the panel.
• close(): Programmatically closes the layer associated with the trigger element.

instance.setTitle('New Title')

FAQs:

Q: Can I open multiple layers at once?
A: Yes. bs-layer supports stacking. Each new layer opens on top, and close() removes the top one. Use $.bsLayer.closeAll() to dismiss all.

Q: How does stacking affect performance on mobile? A: Each layer is a separate element in the DOM. While the library itself is lightweight, having 5 or 6 layers open, each with heavy content, could impact performance. The best practice is to keep the content inside layers reasonable and leverage the AJAX functionality to only load what's needed, when it's needed.

Q: Can I fully customize the look and feel of a layer?
A: Yes. You have two main options. The bgStyle setting lets you pass in custom CSS classes or an object of inline CSS properties. For more complex styling, you can give your layer a unique name and target it directly in your stylesheet with an attribute selector like .bs-layer[data-name="my-custom-layer"] { ... }.

Q: What's the difference between backdrop: true and backdrop: 'static'?
A: This behavior mirrors Bootstrap's modals. With true, clicking the dark backdrop behind the layer will close it. With 'static', clicking the backdrop does nothing.

Q: What happens if AJAX content fails to load?
A: Failed requests trigger the global onError callback. You can customize error handling by overriding $.bsLayer.config.onError with your own function.

Q: What happens if I try to open a layer that’s already open?
A: It blocks the action and logs an error. bs-layer prevents duplicate named layers. Either close the existing one first or use a unique name.

Changelog:

v1.0.6 (2025-08-05)

• Minify bsLayer plugin script to optimize performance and reduce file size for production use.

---

This awesome jQuery plugin is developed by ThomasDev-de. For more Advanced Usages, please check the demo page or visit the official website.