Skip to content

Latest commit

 

History

History
376 lines (325 loc) · 11 KB

README.md

File metadata and controls

376 lines (325 loc) · 11 KB
Raw

v-menu-multi-level


Table of Contents

Introduction

v-menu-multi-level is a customlizable UI Component for VueJS that creates a multi-level menu from a JSON data on a defined structure. The assigned props allows customize this menu using CSS3 properties and change its behavior.

Features:

  • Auto change sub-menu open-direction property when the document body overflows.
  • Set a sorting function for nodes in same level.
  • Open sub-menus in down or right directions.
  • Set icons and its style before or after nodes.
  • Keep a sub-menu opened when click outside from them.
  • Set icons when a sub-menu is opened or closed.
  • Apply CSS3 for hover, active or striped on items.
  • Set a root node visibilty dynamically.
  • Close all opened sub-menus when click outside from them.
  • Set menu alignment for root items.
  • Add prepend and/or append slots for menu.
  • Set a function to be executed when an item is clicked.

Definitions:

  • Node: A JavaScript Object containing a string for a label and an array of zero or more children nodes.
  • Root: First level of the component node's property.
  • Leaf: A node which doesn't have children nodes.
  • Item: A rendered node on HTML.
  • Menu: A rendered collection of all root nodes on HTML.
  • Sub-menu: A rendered collection of one children's node on HTML.

Notes

The generated menu uses the CSS3 property display: flex and its related properties for desktop platforms where the dimension of the menu depends of nodes' label, specially on root items. Any CSS3 property can be passed to container menu directly from component.

The auto open-direction of an item checks if the body's dimension has changed after rendered, so the open-direction property when is set to right is changed to down when it occurs.

Live Demo

Try on CodePen

Installation

yarn add v-menu-multi-level --save

or

npm install v-menu-multi-level --save

Basic Usage

<!-- Vue component -->
<template>
    <v-menu-multi-level :nodes="nodes"></v-menu-multi-level>
</template>

<script>
import VMenuMultiLevel from 'v-menu-multi-level'
import 'v-menu-multi-level/dist/v-menu-multi-level.css'

export default {
  components: {
    VMenuMultiLevel
  },
  data() {
    return {
      nodes: [{
        label: 'North America',
        visible: true,
        children: [{
          label: 'United States',
          children: [{
            label: 'California',
            children: [{
              label: 'Los Angeles',
              children: [{
                label: 'Beverly Hills',
                children: []
              },
              {
                label: 'Hollywood',
                children: []
              },
              {
                label: 'Santa Monica',
                children: []
              }]
            }]
          }]
        }]
        // . . .
      }]
    }
  }
}
</script>

Component Reference

Properties

Property Type Default Description
align String center Alignment of the root items. Possible values: left, right, center, fill
children String children A property name used on children nodes.
container‑items‑style‑down Object View A CSS3 style object for the container items at same level when the open-direction property is down.
container-items-style-right Object View A A CSS3 style object for the container items at same level when the open-direction property is right.
icon-down-after Object View The opened and closed icon properties shown after label. Each one has an icon and its style. Applies to: non-root items and open-direction property is down.
icon-down-before Object View The opened and closed icon properties shown before label. Each one has an icon and its style. Applies to: non-root items and open-direction property is down.
icon-down-before-leaf Object View The icon properties shown before label. It has an icon and its style. Applies to: leaf items and open-direction property is down.
icon-right-after Object View The opened and closed icon properties shown after label. Each one has an icon and its style. Applies to: non-root items and open-direction property is right.
icon-right-before Object View The opened and closed icon properties shown before label. Each one has an icon and its style. Applies to: non-root items and open-direction property is right.
icon-right-before-leaf Object View The icon properties shown before label. It has an icon and its style. Applies to: leaf items and open-direction property is right.
icon-root-after Object View The opened and closed icon properties shown before label. Each one has an icon and its style. Applies to: root items.
icon-root-before Object View The opened and closed icon properties shown before label. Each one has an icon and its style. Applies to: root items.
ignore-sort-root-items Boolean false Ignores sorting root items on *sortItems() function. Possible values: true, false
item-active-style1 Object View A CSS3 style object
item-hover-style1 Object View A CSS3 style object
item-style Object View A CSS3 style object
keep-opened Boolean false Keeps sub-menus opened when opening a new one. Possible values: true, false
label String label A property name used on nodes' label
nodes Object [ ] An array of objects with a label and children nodes
offset-down-direction Number 20 An offset (in pixels) from a parent item when the open-direction property is down
open-direction String right . Possible values: right, down
open-on-leaf-only Boolean true Executes a click event on leaf only. Possible values: true, false
root-item-active-style2 Object View A CSS3 style object
root-item-hover-style2 Object View A CSS3 style object
root-item-position String left Align the edge of the root items with its sub-menu. Possible values: right, left
root-item-style Object View A CSS3 style object
sort-items Function Ascending function sort A sort function that compare two labels properties at same node level which results in -1, 0 or 1
striped-style1 Array View Applies an array of one or more CSS3 objects for items on a submenu resulting on a striped effect

Notes

1Inherits CSS3 properties from itemStyle
2Inherits CSS3 properties from rootItemStyle

Slots

Name Description
append Scoped slot for custom content after the menu.
prepend Scoped slot for custom content before the menu.

Events

Event Arguments Description
click-item event - Native event object.
item - Node of the item clicked.		 Emitted when an item is clicked.

Default Styles

container-items-style-down
{
  border: "solid 1px #eee"
}
container-items-style-right
{
  border: "solid 1px #eee"
}
icon-down-after
{
  opened: {
    icon: "–",
    style: {
      marginLeft: "10px"
    }
  },
  closed: {
    icon: "+",
    style: {
      marginLeft: "10px"
    }
  }
}
icon-down-before
{
  opened: {
    icon: "",
    style: { }
  },
  closed: {
    icon: "",
    style: { }
  }
}
icon-down-before-leaf
{
  icon: "",
  style: { }
}
icon-right-after
{
  opened: {
    icon: "▾",
    style: {
      marginLeft: "10px",
      transform: "rotate(90deg)"
    }
  },
  closed: {
    icon: "▾",
    style: {
      marginLeft: "10px",
      transform: "rotate(-90deg)"
    }
  }
}
icon-right-before
{
  opened: {
    icon: "",
    style: { }
  },
  closed: {
    icon: "",
    style: { }
  }
}
icon-right-before-leaf
{
  icon: "",
  style: { }
}
icon-root-after
{
  opened: {
    icon: "▾",
    style: {
      marginLeft: "10px",
      transform: "rotate(180deg)"
    }
  },
  closed: {
    icon: "▾",
    style: {
      marginLeft: "10px"
    }
  }
}
icon-root-before
{
  opened: {
    icon: "",
    style: ""
  },
  closed: {
    icon: "",
    style: ""
  }
}
item-active-style
{
  color: "#fff",
  backgroundColor: "#444"
}
item-hover-style
{
  backgroundColor: "#e7e7e7"
}
item-style
{
  padding: "6px",
  backgroundColor: "#f5f5f5"
}
root-item-active-style
{
  color: "#fff",
  backgroundColor: "#444"
}
root-item-hover-style
{
  backgroundColor: "#eee"
}
root-item-style
{
  backgroundColor: "#f9f9f9",
  textAlign: "center",
  fontSize: "14px",
  padding: "10px 20px"
}
striped-style
[
  {
    backgroundColor: "#f9f9f9"
  },
  {
    backgroundColor: "#f1f1f1"
  }
]

Browser Compatibility

Browser Version
Chrome 61+
Firefox 60+
Safari 10.1+
Edge 16+
Internet Explorer 11+ ( Polifill needed )

License

MIT

Credits

Developed by Adson Vinicius