# metisMenu

A jQuery menu plugin

Star Fork Download

- Getting started
  - Install
  - Download
- Usage
  - Stopping list opening on certain elements
- Options
  - toggle
  - dispose
  - preventDefault
  - triggerElement
  - parentTrigger
  - subMenu
- Events
- Migrating to v3 from v2
- Demo
- About
  - Related projects
  - Contributors
  - Contributing
  - Release History
  - Author
  - License

(TOC generated by verb using markdown-toc)

## Getting started

### Install

Install with npm:

    $ npm install --save metismenu

Install with yarn:

    $ yarn add metismenu

Install with composer

    $ composer require onokumus/metismenu:dev-master

### Download

download

## Usage

1. Include metismenu StyleSheet

       <link rel="stylesheet" href="https://unpkg.com/metismenu/dist/metisMenu.min.css">
               <!-- OR -->
               <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/metismenu/dist/metisMenu.min.css">

2. Include jQuery

       <script src="https://unpkg.com/jquery"></script>
               <!-- OR -->
               <script src="https://cdn.jsdelivr.net/npm/jquery"></script>

3. Include metisMenu plugin's code

       <script src="https://unpkg.com/metismenu"></script>
               <!-- OR -->
               <script src="https://cdn.jsdelivr.net/npm/metismenu"></script>

4. Add id attribute to unordered list

       <ul id="metismenu">

               </ul>

5. Make expand/collapse controls accessible

   > Be sure to add `aria-expanded` to the element `a`. This attribute explicitly defines the current state of the collapsible element to screen readers and similar assistive technologies. If the collapsible element is closed by default, it should have a value of `aria-expanded="false"`. If you've set the collapsible element's parent `li` element to be open by default using the `mm-active` class, set `aria-expanded="true"` on the control instead. The plugin will automatically toggle this attribute based on whether or not the collapsible element has been opened or closed.

       <ul id="metismenu">
                <li class="mm-active">
                  <a href="#" aria-expanded="true">Menu 1</a>
                  <ul>
                  ...
                  </ul>
                </li>
                <li>
                  <a href="#" aria-expanded="false">Menu 2</a>
                  <ul>
                  ...
                  </ul>
                </li>
                ...
                </ul>

6. Arrow Options

   > add `has-arrow` class to `a` element

       <ul id="metismenu">
               <li class="mm-active">
                <a class="has-arrow" href="#" aria-expanded="true">Menu 1</a>
                <ul>
                ...
                </ul>
               </li>
               <li>
                <a class="has-arrow" href="#" aria-expanded="false">Menu 2</a>
                <ul>
                ...
                </ul>
               </li>
               ...
               </ul>

7. Call the plugin:

        $("#metismenu").metisMenu();

### Stopping list opening on certain elements

Setting aria-disabled="true" in the `<a>` element as shown will stop metisMenu opening the menu for that particular list. This can be changed dynamically and will be obeyed correctly:

    <a href="#" aria-expanded="false" aria-disabled="true">List 1</a>

## Options

#### toggle

Type: `Boolean` Default: `true`

For auto collapse support.

     $("#metismenu").metisMenu({
               toggle: false
             });

#### dispose

Type: `String` Default: `null`

For stop and destroy metisMenu.

     $("#metismenu").metisMenu('dispose');

#### preventDefault

Type: `Boolean` Default: `true`

> Prevents or allows dropdowns' onclick events after expanding/collapsing.

       $("#menu").metisMenu({
                 preventDefault: false
               });

since from version 2.7.0

#### triggerElement

Type: `jQuery selector` Default: `a`

     $("#metismenu").metisMenu({
               triggerElement: '.nav-link' // bootstrap 4
             });

#### parentTrigger

Type: `jQuery selector` Default: `li`

     $("#metismenu").metisMenu({
               parentTrigger: '.nav-item' // bootstrap 4
             });

#### subMenu

Type: `jQuery selector` Default: `ul`

     $("#metismenu").metisMenu({
               subMenu: '.nav.flex-column' // bootstrap 4
             });

## Events

Event Type | Description
--- | ---
show.metisMenu | This event fires immediately when the `_show` instance method is called.
shown.metisMenu | This event is fired when a collapse `ul` element has been made visible to the user (will wait for CSS transitions to complete).
hide.metisMenu | This event is fired immediately when the `_hide` method has been called.
hidden.metisMenu | This event is fired when a collapse `ul` element has been hidden from the user (will wait for CSS transitions to complete).

## Migrating to v3 from v2

- Update `metisMenu.js` & `metisMenu.css` files
- Change `active` class to `mm-active`

### Author

Osman Nuri Okumus

- github/onokumus
- twitter/onokumus

### License

Copyright © 2018, Osman Nuri Okumus.
Released under the MIT License.