README

DeepNav

The purpose of DeepNav is to provide a flexible, multilevel, drop-in navigation system that requires minimal in-HTML markup. DeepNav supports as many levels of navigation as good taste will allow, and then some. You need only set up a couple of divs and anchors, initialize DeepNav, and you're good to go!

Features:

As many nested levels of navigation as you dare
Options for click-to-open menus, hover-only menus, or top-level hovering with clickable submenus
Easy-to-implement responsivity
Easily stylable and highly customizable

Check out the CodePen example to play around with settings and styling.

Development
Installation
Implementation
Styling

Development

Author: Jacob Runge

Check out my website, JacobRunge.com
See the code on GitHub
Get the Node package via NPM

Support the developer!

This code is provided under the MIT license, and is completely free to use and modify in any personal or commercial projects--just because I like you! If you are using this code in an application that is making you money, or even if you just think it's super neat and want to support me as a developer, consider a small tip at the "Buy me a coffee!" link below. It's much appreciated! :-)

Installation

Via NPM

Install via NPM: npm install @jwrunge/deepnav

Or download a local copy of the code here.

Implementation

The JavaScript

There are two ways to implement DeepNav:

Including as a script tag
Including as a module

Importing via script tag is easy-peasy:

<script src="path/to/deepnav.js">
<script>
    new deepnav("myNav", {options})
</script>

If importing via NPM or in a module:

<script type="module">
    import deepnav from '@jwrunge/deepnav'
    new deepnav("myNav", {options})
</script>

The first argument to deepnav() should be the ID of the navigation structure you want to convert to a DeepNav navigation system. The second argument is a JavaScript dictionary, where you can pass various customization options to deepnav (detailed in "Customization" below).

The HTML

The HTML markup of your navigation structure should consist of a root div with an ID that you pass to the new deepnav() constructor. To create a sub-list of links, nest an <a> tag with the class deepnav-link, followed by a div with the class .sublinks. An example:

<div id='myNav'>
    <a href="some/cool/place">Leve 1 terminal link</a>

    <a class='deepnav-link'>Level 1 submenu link</a>
    <div class='sublinks'>
        <a href="another/cool/place">Level 2 terminal link</a>

        <a class='deepnav-link'>Level 2 submenu link</a>
        <div class='sublinks'>
            <a href="a/third/cool/place">Level 3 terminal link</a>
        </div>
    </div>
</div>

In the above example, DeepNav would create a menu system with two root-level links, one terminal link and one that opens a submenu. The submenu then would contain two links, one terminal link and one that opens a submenu. That submenu would then open a third-level terminal link.

Customization

The following is a list of customization options, which you can pass in a JavaScript dictionary to the second parameter of the deepnav() constructor.

You can change any of these preferences on the fly if you set up a reference to your DeepNav instance (var myNav = new deepnav('coolId')) by altering myNav.settings.settingIWantToChange.

prop	default	description
hoverMode	""	Possible values include 'all', 'top_only', or any falsey value. This determines whether or not your anchors will open submenus on hover (they always respond to 'click'). 'all' signifies that all anchors will open submenus on hover (this is really a nightmare with a stacked menu); 'top_only' means that only your top-level anchors will respond to hover (you have to click on submenu anchors); false means users have to click.
alignSubmenus	"center"	Possible values include 'right', 'left', and 'center'. This affects how dropdown menus are displayed relative to the anchor when DeepNav is not in 'stacked' mode (i.e. a horizontal rather than a vertical menu). No worries--DeepNav will do its best not to let your menu go off-screen; if a menu is aligned 'left' and goes off-screen to the right, DeepNav will automatically change alignment to 'right' for that menu.
showContentArrows	true	Possible values include boolean true or false. This determines whether or not DeepNav adds open/close arrows to submenus. You MUST encode your HTML with UTF-8 (meta charset='utf-8' in the document head) for this to work anywhere outside of Chrome.
showDefaultAnimations	true	Possible values include boolean true or false. This determines whether or not DeepNav is allowed to animate the opening and closing of your submenus. For the most part, I think the animations are sufficient for most designs.
showAestheticStyling	true	Possible values include boolean true or false. You may want to set this one to false to give you full control over the aesthetic styling, although it is simple to override these styles if you wish to include them as a jumping off point.
displayMode	"responsive"	Possible values include 'reponsive', 'horizontal', and 'stacked'. 'horizontal' will leave the menu in horizontal mode (best for wide screens); 'stacked' will leave the menu in 'stacked'/vertical mode (best for mobile devices in, say, a hamburger menu). 'responsive' will adapt itself between 'stacked' and 'horizontal' based on a breakpoint. 'responsive' also plays with the navigation style when your menu is in Hover Mode, removing hover functionality while the menu is stacked.
breakpoint	500	A number value. This defines the pixel width at which your menu changes from horizontal to stacked while in the responsive Display Mode.

Styling

DeepNav programmatically sets some initial styles for each instance of DeepNav that you invoke. These styles are placed at the beginning of your document head so that they can be overridden easily, but if you need to make changes that the aesthetic styles are disallowing, you can disable them via the customization options listed above. You will need to do a bit more work to get your navigation system looking good, however!

Important styling classes: I have included the most important classes for custom CSS styling below. This is not an exhaustive list, but your browser's inspector will likely give you the best idea of what to style for your specific use case.

class	description
.sublinks	A `div` containing anchor links and possibly other `.sublinks`.
.deepnav-link	A link that opens a `.sublinks` container.
.nav-list-open	Applied to a `.deepnav-link` to indicate that the submenu is open.
.stacked	Applied to the root DeepNav `div` when it is displayed in stacked mode.

@jwrunge/deepnav

Usage no npm install needed!