Simpler-sidebar NPM

simpler-sidebar

A jQuery plugin that allows to create a side nav as in modern mobile apps. It aims to simplicity so that everybody can use it no matter if expert programmers or not.

:muscle: works with

jQuery v1.12.4
jQuery v2.2.4
jQuery v3.1.0

Latest Release

v2.2.5 (2018-03-05):
- update dependencies

Important notes about the latest release

If you are still using the v1.x.x, please, consider to update the plugin to the latest v2.x.x.

Before updating your local simpler-sidebar package, be sure to read the changelog too, especially the latest major update changelog. Upgrading without migrating will broke your scripts.

Navigate

Download

Run one of these commands in your bash according to your needs.

git clone https://github.com/simple-sidebar/simpler-sidebar.git

npm install simpler-sidebar

Or download the latest version from the releases page.

If you are updating, remember to read the Release History and to check for incompatibility issues.

Getting Started

You will need to prepare a specific HTML template in order to make it work properly. The code below is just an example from which you can and have to draw inspiration. Along with this plugin you are provided with some demo pages in the demo directory.

<div id="navbar">
  <!--
  #navbar is positioned fixed.

  It does not matter what kind of element #toggle-sidebar is.
  -->
  <span id="toggle-sidebar" class="button icon">ITEM</span>
</div>

<div id="sidebar">
  <!--
  simpler-sidebar will handle #sidebar's position.

  To let the content of your sidebar overflow, especially when you have a lot of content in it, you have to add a "wrapper" that wraps all content.

  TIP: provide a background color.
  -->
  <div id="sidebar-wrapper" class="sidebar-wrapper">
    <!--
    Links below are just an example. Give each clickable element, for example links, a class to trigger the closing animation.
    -->
    <a class="close-sidebar" href="#">Link</a>
    <a class="close-sidebar" href="#">Link</a>
    <a class="close-sidebar" href="#">Link</a>
    <a class="close-sidebar" href="#">Link</a>
  </div>
</div>

If you add the sidebar-wrapper (and you should), remember to give it this style attributes:

.sidebar-wrapper {
  position: relative;
  height: 100%;
  overflow: auto;
}

At the bottom of the web page, just before the </body> tag, include the jQuery library. If you are interested in better easing, include the jQuery-UI library too. Eventually include simpler-sidebar.

<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
<script src="simpler-sidebar/dist/jquery.simpler-sidebar.min.js"></script>

Call the simpler-sidebar plugin function and fill it with the options you need. Here is an example of some required options. Read the Options section for further informations.

<script>
    $( document ).ready( function() {
        $( "#sidebar" ).simplerSidebar( {
            selectors: {
                trigger: "#toggle-sidebar",
                quitter: ".close-sidebar"
            }
        } );
    } );
</script>

Options

To customize the plugin, add the desired option in the plugin itself.

The options are stored in a javascript object, so you have to take care of javascript grammar while tweaking the plugin.

$( "#sidebar" ).simplerSidebar( {
    selectors: {
        trigger: "#toggle-sidebar",
        quitter: ".close-sidebar"
    },
    animation: {
        easing: "easeOutQuint"
    },
    sidebar: {
        width: 500
    },
    mask: {
        display: false
    }
} );

Options List

Check out all available options in the options list documentation page too and use the example above as reference.

Contributing

Help me improve simplerSidebar and make it as perfect as possible, but first read the contribution guidelines.

Release History

Check out all releases in the Release History documentation page.

If you are still using the v1.x.x, please, consider to update the plugin to the latest v2.x.x.

Before updating your local simpler-sidebar package, be sure to read the changelog too, especially the latest major update changelog. Upgrading without migrating will broke your scripts.