amirkian007 / vue-awesome-sidebar

A Modern and Fast sidebar Menu component for vue(3x) capable with vue-router.

Vue Awesome Sidebar

About

Vue Awesome Sidbar is a powerfull, fast vue js(3x) sidbar navigation library with a set of components and slots that are flexible and customizable using sass and css which is very easy to use.

Demo

Check out Live demo at amirkian007.github.io/vasmenu

Features

• Built with typescript and vite with 0 dependants.
• Support for vue.js (3x) and nuxt.js (3x).
• Customization support for every component slots , CSS and SASS.
• Capable with Vue-router.
• Multiple Menu types(more will be added in the future).
• Complete RTL support.
• Dark and White mode support.
• Responsive design.

Table of Contents

• Demo
• Installation
• Basic Usage
• Api
  • Props
  • Events
  • Slots
• Styling
  • Sass varibales
  • Css
• Author
• License

Installation

npm i vue-awesome-sidebar --save

or

yarn add vue-awesome-sidebar --save

Install the component globally.

Vue js 3:

//main.js
import { createApp } from 'vue'
import App from './App.vue'
import vueAwesomeSidebar from 'vue-awesome-sidebar'
import 'vue-awesome-sidebar/dist/vue-awesome-sidebar.css'

const app = createApp(App)
app.use(vueAwesomeSidebar)
app.mount("#app")

Nuxt js 3:

import vueAwesomeSidebar from "vue-awesome-sidebar";
import "vue-awesome-sidebar/dist/vue-awesome-sidebar.css";
export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(vueAwesomeSidebar);
});

or Install the component loacally :

//App.vue
import vueAwesomeSidebar from 'vue-awesome-sidebar'
import 'vue-awesome-sidebar/dist/vue-awesome-sidebar.css'
export default {
  components: {
    vueAwesomeSidebar
  }
}

Basic Usage

a simple example would be like this : check out props for properites

NOTE : you have to load the icons separately like loading material-icons files with cdn

<template>
  <VueAwesomeSideBar
      v-model:miniMenu="miniMenu"
      v-model:collapsed="collapsed"
      :menu="testMenu"
      vueRouterEnabel
    ></VueAwesomeSideBar>
</template>

<script setup>
import { ref } from 'vue'

const collapsed = ref(false)
const miniMenu = ref(false)

const testMenu = [
  {
    name: 'Getting Started',
    icon: { text: 'home' , class: 'material-icons-outlined' },
    children: [
      {
        name: 'level 1.1',
        href: '/a',
        icon: { text: 'home' , class: 'material-icons-outlined'},
        children: [
          {
            href: '/b',
            name: 'level 1.1.1',
          },
        ]
      },
      {
        name: 'level 1.2'
      }
    ],
  },
  {
    header: 'Settings'
  },
  {
    name: 'Dashboard',
    icon: { class: 'material-icons-outlined', text: 'dashboard' },
    children: [
      {
        href: '/c',
        name: 'level 2.1',
      },
    ]
  },
  {
    name: 'close menu',
    icon: { text: 'settings', class: 'material-icons-outlined' },
  },
]
</script>

Api

Props

Prop	Type	Default	Description
menu	Array	null	required - Array list of item properties
menuType	string	simple	style of the menu can be either "fully" or "simple"
collapsed	Boolean	false	sets menus collapsed state - should be used with v-model
miniMenu	boolean	false	sets mini menus state - should be used with v-model
width	string	290px	sets width for menu
widthMiniMenu	string	65px	sets width for miniMenu
autoCollapse	number	null	adds event listner to collapse menu when the given value(in px) is lower than the viewport width
closeOnClickOutSide	Boolean	false	Adds event listner to collapse Menu when outside is clicked
overLayerOnOpen	Boolean	false	Adds overlayer under the Menu when the menu is open - usefull on mobile
childrenOpenAnimation	Boolean	true	opens menu items children with animation
keepChildrenOpen	Boolean	flase	keeps children items opened when parent item is closed
position	string	fixed	sets menu positiong - by default menu is fixed on viewport
ChildrenOpenActiveRoute	Boolean	true	opens meneitem children on page-load if an item with active "href" inside and miniActive class is applied
checkButtonActive	Boolean	true	checks if menuitems href is active, if so activeClass is added to it and miniActive class to the parent
vueRouterEnabel	Boolean	true	when a meueitem is clicked vue-router will pushe the route to the items "href" property
BottomMiniMenuBtn	Boolean	true	Adds mini menu toggle bottom to bottom of menu
paddingTop	String	0px	Adds padding to top of menu - usefull when using with app bar with higher z-index
dark	Boolean	false	makes the theme of menu dark - color can be customized with sass vars
rtl	Boolean	false	Makes the entire menu right to left align
closeOpenMenuOnHrefPush	Boolean	false	close MenuItems with children that are expanded on router/herf push

menu properties

interface MenuItem {
  href: string | object // vue-router Object
  name: string
  icon?: MenuItemIcon
  children?: Array< MenuItem | MenuHeaderItem >
  class?: string
  collapseOnClick?: boolean //collapses menu when clicked - this behavior can also be achieved with Events
  activeClass?: boolean
  miniActiveClass?: boolean
}

interface MenuItemIcon {
  text: string
  class?: string
  element?: string //defualt is <i>
  attributes?: object
}

interface MenuHeaderItem {
  title: string
  class?: string
  attributes?: object
}

interface MenuLine {
  LineShow: boolean
  class?: string
  attributes?: object
  element?: string
}

Events

Event Name	Description
@item-click(MenuItem)	fired when a menu item is clicked
@update:collapsed(isCollapsed)	fired when menu collapse state changes - should be used with "v-model"
@update:miniMenu(isMiniMenu)	fired when mini menu state changes - should be used with "v-model"

Slots

<!--menu items Append icon-->
<template #itemApendIcon="{ icon,isChildrenMenuOpen, active,miniActive }"></template>
<!--menu items label -->
<template #menuItemLabel="{labelName ,isChildrenMenuOpen, active,miniActive}"></template>
<!--menu items Preppend icon-->
<template #itemPrepandIcon="{ icon,isChildrenMenuOpen, active,miniActive }"></template>
<!--menu header item-->
<template #headerItem="{ header }"></template>
<!--menu header at the top of the menu-->
<template #header></template>
<!--menu footer -->
<template #footer></template>
<!--menus bottom toggle btn -->
<template #BottomMiniMenuBtn></template>

Styling

Sass varibles

to use sass varibles import the SCSS file insted of Css, then import custom varibles, example:

//style.scss
@import "custom-var.scss";
@import "vue-awesome-sidebar/src/scss/vue-awesome-sidebar.scss";

//main.js
import vueAwesomeSidebar from 'vue-awesome-sidebar'
//import 'vue-awesome-sidebar/dist/vue-awesome-sidebar.css'
import './style.scss'

Sass varibles:

//z-index of the menu components rage form 848-854

//<--BASE-->
$overlayer-bg-color: rgba(0, 0, 0, 0.6);
$toggle-mini-btn-height: 50px;
$menu-item-simpleType-icon-height: 35px;
$menu-item-fullyType-height: 44px;
$label-font-size: 16px;//may not work with slots
$label-icon-size: 20px;//may not work with slots
$scroll-bar-width: 13px;

//<--COLORS-->
//NOTE : the "-white" at the end of each var defines the theme, you can change it to "-dark" to set it for dark mode theme
//example :"$icon-color-dark : #000000 " for dark theme and "$icon-color-white : #fafafa " for white theme
//note : may not work with slots depending on how the slots is used

//Menu
$menu-back-ground-color-white: white; -dark: #0d1117; //==> $menu-back-ground-color-dark:#0d1117
$border-color-white: #cfcfcf; -dark: rgba(170, 170, 170, 0.329);
$scroll-bar-color-white: rgb(184, 184, 184); -dark: #686868;
$header-color-white: #213547; -dark: #ffffffde;

//Menu item prepend icon
$icon-color-white: rgb(28, 30, 33); -dark: rgb(218, 221, 225);
$icon-active-color-white: #2c7ae0; -dark: rgb(44, 122, 224);
$icon-mini-active-color-white: #2c7ae0; -dark: rgb(44, 122, 224);
$icon-hover-color-white: ''; -dark: '';

//Menu item
$menu-item-bg-color-white: none; -dark: none;
$menu-item-hover-bg-white: rgb(242, 242, 242); -dark: hsla(0, 0%, 100%, 0.05);
$menu-item-active-bg-color-white: rgb(242, 242, 242); -dark: hsla(0, 0%, 100%, 0.05);
$mini-active-item-bg-color-white: none; -dark: none;

//Menu item label
$text-color-none-hover-white: rgb(28, 30, 33); -dark: rgb(218, 221, 225);
$text-active-color-white: #2c7ae0; -dark: rgb(44, 122, 224);
$text-mini-active-color-white: #2c7ae0; -dark: rgb(44, 122, 224);
$text-hover-color-white: none; -dark: none;

//menu item append icon
$append-icon-color-white: rgb(28, 30, 33); -dark: rgb(218, 221, 225);
$append-active-icon-color-white: rgb(28, 30, 33); -dark: rgb(218, 221, 225);

//horizental line
$hr-line-color-white: rgba(211, 211, 211, 0.548); -dark: rgba(211, 211, 211, 0.548);

//bottomBtn for miniMenu
$bottomBtn-bg-color-white: white; -dark: #13161b;

Css class

//menu
.vas-menu{}
.menu-wraper{}//menu scroll wrapper
.miniCoolapseMenu{} //for mini menu
.compeleteCoolapseMenu{} //for collapsed menu
.dark-theme{}
.white-theme{}
.vas-footer{}
.bottomBtn{} // mini menutoggle button

//menu item
.menu-item-base{// wrapper for menu item ant children
  &.menuExpanded
}//apllayed to all menuitem
.menuExpanded{}
.label{
  .menu-icond{}
  .labelName{}
  .icons{}
  .postIconOpenAnima{}
}
.menuexpand{}
.activeClass{}
.miniActiveClass{}
.labelHoverClass{}

//container
.items-container{}
.topContainer{}

Contributing

$ pnpm i
# dev server
$ pnpm run dev

License

vue-awesome-sidebar is open-sourced software licensed under the MIT license.