Skip to content

Latest commit

 

History

History
350 lines (299 loc) · 11.6 KB

README.md

File metadata and controls

350 lines (299 loc) · 11.6 KB

Vue Awesome Sidebar

vue-wesome-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

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
keepOneMenuOpenAtAtime Boolean false keep one open menu at a time

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.