Skip to content

README.md

Latest commit

 

History

History
139 lines (107 loc) · 4.65 KB

README.md

File metadata and controls

139 lines (107 loc) · 4.65 KB
Raw

@dcdavidev/jquery-sidenav

A robust, flexible, and simple-to-use side navigation plugin for jQuery. Designed to mimic modern mobile application sidebars, it handles everything from basic animations to page freezing and background masks.

Features

  • 📱 Mobile-Ready: Smooth animations optimized for a native-like feel.
  • ⚙️ Highly Configurable: Control width, alignment, animation easing, and more.
  • 🧊 Page Freezing: Optionally prevent background scrolling when the menu is open.
  • 🎭 Auto-Masking: Automatically generates a clickable background mask to close the menu.
  • ⌨️ TypeScript Powered: Fully typed for a better developer experience.

Installation

Install the package via your preferred package manager:

# pnpm
pnpm add @dcdavidev/jquery-sidenav

# npm
npm install @dcdavidev/jquery-sidenav

# yarn
yarn add @dcdavidev/jquery-sidenav

Dependencies

This plugin requires jQuery (v4.0+) and jQuery UI (for animation easing).

<script src="https://code.jquery.com/jquery-4.0.0.min.js"></script>
<script src="https://code.jquery.com/ui/1.14.0/jquery-ui.min.js"></script>

Quick Start

1. HTML Structure

Your sidebar needs a trigger (toggler) and the navigation container itself.

<!-- The App Bar / Header -->
<header>
  <button id="toggle-sidenav">Menu</button>
</header>

<!-- The Sidenav -->
<nav id="sidenav">
  <div class="sidenav-wrapper">
    <button class="quit-sidenav">Close Menu</button>
    <ul>
      <li><a href="#">Home</a></li>
      <li><a href="#">About</a></li>
      <li><a href="#">Contact</a></li>
    </ul>
  </div>
</nav>

2. Basic Initialization

Initialize the plugin by targeting your sidenav element:

$(document).ready(function () {
  $('#sidenav').sidenav({
    toggler: '#toggle-sidenav',
    quitter: '.quit-sidenav',
  });
});

Advanced Usage

Handling Content Overflow

By default, the sidenav has a fixed height. If your menu is long, you should wrap your content in a container with scrolling enabled:

#sidenav .sidenav-wrapper {
  height: 100%;
  overflow-y: auto;
}

Using Event Callbacks

You can hook into the lifecycle of the sidenav to trigger custom logic:

$('#sidenav').sidenav({
  toggler: '#toggle-sidenav',
  events: {
    onOpen: function () {
      console.log('Sidenav is starting to open!');
    },
    afterClose: function () {
      console.log('Sidenav is now fully closed.');
    },
    always: function () {
      // Triggered on every state change
      $('#toggle-sidenav').toggleClass('is-active');
    },
  },
});

Options

Option Type Default Description
toggler string '' Required. Selector for the element that toggles the menu.
quitter string 'a' Selector for elements inside the menu that will close it when clicked.
align 'left' | 'right' 'left' Which side the menu appears on.
width number 300 Width of the menu in pixels.
gap number 64 The minimum gap left between the menu and the screen edge on small devices.
open boolean false Whether the menu should be open on initialization.
zIndex number 3000 The z-index of the sidenav element.
freezePage boolean true Set body overflow to hidden when the menu is open.
animation.duration number 500 Animation speed in milliseconds.
animation.easing string 'swing' jQuery UI easing function name.
mask.display boolean true Whether to show the background overlay.
mask.css object See below Custom CSS for the mask element.

Default Mask CSS

{
  backgroundColor: 'black',
  opacity: 0.5,
  filter: 'Alpha(opacity=50)'
}

License

MIT © Davide Di Criscito