ml-stack-nav
v1.1.3
Published
Customizable, responsive, accessible, easy-to-use multi-level stack navigation menu with slide effect.
Downloads
26
Maintainers
damianwajerReadme
Multi-level stack navigation (jQuery mlStackNav)
Customizable, accessible, easy-to-use multi-level stack navigation menu.
The purpose behind this project is to provide a fully functional, responsive and usable navigation with minimal styling, which can also be used as a good starting point to implement your own custom design.
Demo
https://damianwajer.github.io/ml-stack-nav/
Requirements
- jQuery >= 1.7
Browser support
- All modern browsers such as Chrome, Firefox, Safari, Edge (last 2 versions) and Internet Explorer 10+
- Stock browser on Android 4.0+ and Safari on iOS 7+
- Internet Explorer 9 is also supported but without transition animations and with some additional CSS (I recommend placing IE 9 rules within conditional comment in
<head>section of the HTML file or in some separate.cssfile with other IE 9 fixes):
<!--[if IE 9]>
<style type="text/css">
.ml-stack-nav {
display: none;
}
.ml-stack-nav.is-open {
display: block;
}
</style>
<![endif]-->Download
- via bower:
bower install ml-stack-nav - via npm:
npm install ml-stack-nav - from the releases page
Usage
To get started just add required styles:
<link rel="stylesheet" href="dist/ml-stack-nav.css">Include jQuery:
<script src="//code.jquery.com/jquery-3.3.1.min.js"></script>…and the plugin JS file:
<script src="dist/ml-stack-nav.js"></script>Navigation HTML markup should be placed at the top-level position directly under the body element in the document to avoid the stacking context issues.
<body>
<nav class="ml-stack-nav js-ml-stack-nav">(…)</nav>
</body>Please see index.html file for demo and code example.
Finally, initiate the plugin:
$(".js-ml-stack-nav").mlStackNav();The dist/ml-stack-nav.js and dist/ml-stack-nav.css files contain all what is necessary for the menu to work properly and they should not be edited directly. Unlike them, dist/ml-stack-nav-theme.css theme file provides example styles for the navigation and can be edited, extended or completely replaced with your own styles (the minified files .min.css and .min.js are also available in dist directory and you can use them on production instead of regular ones).
Advanced usage
The goal behind the mlStackNav is to provide a good starting point to implement navigation with custom design, so advanced usage is highly recommended. In order to take full advantage of the mlStackNav, please keep in mind its most important features:
- separation of the appearance and the functionality
- CSS class names according to BEM methodology
- state rules inspired by SMACSS (Scalable and Modular Architecture for CSS)
js-prefixed classes to decouple JavaScript classes from CSS ones
Multiple instances
Multi-level stack navigation also supports multiple instances of the menu.
You can use it to implement as many navigation menus as you want by simply initializing different menus with separate toggle buttons. For example:
$(".js-ml-stack-nav").mlStackNav({
navToggleSelector: ".js-ml-stack-nav-toggle"
});
$(".js-ml-stack-nav-2").mlStackNav({
navToggleSelector: ".js-ml-stack-nav-2-toggle"
});or by providing jQuery selector inside data-nav-toggle attribute:
<button type="button" class="ml-stack-nav-toggle" id="ml-stack-nav-toggle-1">(…)</button>
<nav class="ml-stack-nav js-ml-stack-nav" data-nav-toggle="#ml-stack-nav-toggle-1">(…)</nav>
<button type="button" class="ml-stack-nav-toggle" id="ml-stack-nav-toggle-2">(…)</button>
<nav class="ml-stack-nav js-ml-stack-nav" data-nav-toggle="#ml-stack-nav-toggle-2">(…)</nav>Navigation with JavaScript disabled
mlStackNav can still works in its basic form even when JavaScript is disabled. You just need to make sure that:
no-jsclass is present on the top-level element on your page (e.g. onhtmlelement:<html class="no-js">no-jsis removed before mlStackNav initialization, e.g.$("html").removeClass("no-js")- a link with the anchor matching the navigation
idis used instead of a button (e.g.<a href="#ml-stack-nav-1" class="ml-stack-nav-toggle">and<nav id="ml-stack-nav-1" class="ml-stack-nav js-ml-stack-nav">)
Options
navToggleSelector
Type: String
Default: .ml-stack-nav-toggle
jQuery selector with toggle button element (or a link).
openClass
Type: String
Default: is-open
Class name for open menu items (also background items below current level).
activeClass
Type: String
Default: is-active
Class name for currently active menu item and active toggle button.
zIndexValue
Type: Number
Default: 900
CSS z-index property for navigation menu container.
Methods
Using methods you can interact with the plugin programmatically from within your scripts, e.g. you can open or close the navigation on some custom event.
Available methods:
openOpen the navigation.closeClose the whole navigation.toggleOpen the navigation if it's closed, close if it's open.moveBackMove to the previous menu level.isOpenCheck if the navigation is currently open.
Example:
$(".ml-stack-nav__link").on("click", function () {
$(".js-ml-stack-nav").mlStackNav("close");
});Events
Using events you can run some custom code, e.g. when menu opens or closes.
show.ml-stack-navThis event is triggered before the navigation opens (immediately when theopenmethod is called).hide.ml-stack-navThis event is triggered before the navigation closes (immediately when theclosemethod is called).
Example:
$(".js-ml-stack-nav")
.on("show.ml-stack-nav", function (e) {
console.log(e);
alert("The navigation will open!");
})
.on("hide.ml-stack-nav", function (e) {
console.log(e);
alert("The navigation will close!");
});TODO
- add swipe support
- off-canvas mode (push)
- more themes
- tests
Support
Please open an issue for support.
Contributing
Please contribute using Github Flow. Create a branch, add commits, open a pull request.