@sena-services/vue-left-sidebar

A highly customizable, prop-driven left sidebar component for Vue 3 applications. Features collapsible sections, hover expansion, custom icons, and full theming support.

✨ Features

• 🎨 Fully Customizable - Colors, fonts, spacing, and branding via props
• 📱 Responsive Design - Works on desktop and mobile
• 🔄 Multiple Modes - Auto, collapsed, or expanded states
• 🎯 Icon Integration - Support for custom icon components
• 📊 Navigation Groups - Organized sections with collapsible items
• ⚡ Vue 3 Composition API - Modern Vue.js architecture
• 🎭 Hover Effects - Smooth animations and transitions
• 📦 Tree Shakable - Import only what you need

📦 Installation

npm install @sena-services/vue-left-sidebar
# or
yarn add @sena-services/vue-left-sidebar

🚀 Quick Start

Basic Usage

<template>
  <LeftSidebar
    :navigation-groups="navigationGroups"
    :top-logo-image="'/path/to/logo.png'"
    :brand-name="'Your App'"
    :brand-subtitle="'Dashboard'"
    @component-event="handleNavigation"
  />
</template>

<script setup>
import { ref } from 'vue'
import { LeftSidebar } from '@sena-services/vue-left-sidebar'

const navigationGroups = ref([
  {
    groupId: 'main',
    groupLabel: 'MAIN',
    items: [
      { label: 'Dashboard', to: '/dashboard', icon: 'dashboard' },
      { label: 'Settings', to: '/settings', icon: 'cog' }
    ]
  }
])

const handleNavigation = (event) => {
  console.log('Navigation:', event)
  // Handle navigation logic
}
</script>

With Custom Styling

<template>
  <LeftSidebar
    :navigation-groups="navigationGroups"
    :top-logo-image="logoUrl"
    :brand-name="'Sentra'"
    :brand-subtitle="'Administrator'"
    :primary-color="'#3b82f6'"
    :hover-color="'#efe7dc'"
    :sidebar-background-color="'#ffffff'"
    :font-family="'Inter, sans-serif'"
    :sidebar-mode="'auto'"
    @component-event="handleNavigation"
  />
</template>

📋 Props

Required Props

| Prop | Type | Description | |------|------|-------------| | navigationGroups | Array | Array of navigation group objects | | topLogoImage | String | URL/path to the logo image |

Optional Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | brandName | String | 'Sentra' | Brand name displayed next to logo | | brandSubtitle | String | 'Administrator' | Subtitle displayed below brand name | | primaryColor | String | '#3b82f6' | Primary color for active states and accents | | defaultTextColor | String | '#6c757d' | Default text color | | activeTextColor | String | '#ffffff' | Text color for active/selected items | | brandNameColor | String | '#212529' | Color for the brand name | | sidebarBackgroundColor | String | '#ffffff' | Background color of the sidebar | | hoverColor | String | '#efe7dc' | Background color on hover | | fontFamily | String | 'Inter, system-ui, sans-serif' | Font family | | fontSize | String | '14px' | Base font size | | fontWeight | String | '400' | Base font weight | | sidebarMode | String | 'auto' | Sidebar behavior: 'auto', 'collapsed', 'expanded' | | initialCollapsed | Boolean | true | Initial collapsed state for auto mode | | autoExpandDelay | Number | 200 | Delay before auto-expansion on hover (ms) |

UCC Standard Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | Array | [] | Child components (UCC standard) | | uid | String | null | Unique identifier | | path | String | null | Component path | | addStyles | String | '' | Additional CSS classes | | overrideStyles | Object | {} | Inline style overrides |

📊 Navigation Groups Structure

const navigationGroups = [
  {
    groupId: 'general',        // Unique identifier
    groupLabel: 'GENERAL',     // Display name
    items: [
      {
        label: 'Dashboard',     // Display text
        to: '/dashboard',       // Route path
        icon: 'dashboard'       // Icon identifier
      },
      // ... more items
    ]
  },
  // ... more groups
]

🎨 Sidebar Modes

Auto Mode (Default)

• Collapsed by default
• Expands on hover
• Auto-collapses when mouse leaves

Collapsed Mode

• Always collapsed
• Shows only icons
• No hover expansion

Expanded Mode

• Always expanded
• Shows icons and text
• Fixed width

🎭 Events

component-event

Emitted when navigation items are clicked or sidebar state changes.

// Event structure
{
  eventName: 'navigationLinkClick',
  payload: {
    link: { label: 'Dashboard', to: '/dashboard', icon: 'dashboard' },
    groupId: 'general',
    index: 0,
    timestamp: 1640995200000
  },
  sourcePath: 'sidebar.navigation'
}

🎨 Styling

The component uses CSS custom properties (v-bind) for dynamic styling. All colors and fonts can be customized via props.

Custom CSS Classes

You can add custom styles using the addStyles prop:

<LeftSidebar
  :navigation-groups="groups"
  add-styles="custom-sidebar shadow-lg"
/>

🔧 Advanced Usage

With Vue Router

<script setup>
import { useRouter } from 'vue-router'

const router = useRouter()

const handleNavigation = (event) => {
  if (event.eventName === 'navigationLinkClick') {
    router.push(event.payload.link.to)
  }
}
</script>

With Custom Icons

The component supports custom icon components. Map your icon names in the navigation groups:

const navigationGroups = [
  {
    groupId: 'main',
    groupLabel: 'MAIN',
    items: [
      { label: 'Dashboard', to: '/dashboard', icon: 'custom-dashboard-icon' },
      { label: 'Users', to: '/users', icon: 'custom-users-icon' }
    ]
  }
]

📱 Responsive Design

The sidebar automatically adapts to different screen sizes:

• Desktop: Full functionality with hover effects
• Mobile: Optimized spacing and touch-friendly interactions

🛠️ Development

# Clone the repository
git clone https://github.com/your-org/vue-left-sidebar.git

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests.

📞 Support

For issues and questions, please use the GitHub Issues page.

Made with ❤️ by Sena Services