syncfusion-angular-sidebar

# Implementing Syncfusion Angular Sidebar Component The **Sidebar** is an expandable and collapsible navigation component that acts as a side container for primary or secondary content alongside main content. It supports flexible show/hide behavior, multiple positioning modes (left, right, top, bottom), various expand types (Push, Slide, Over, Auto), docking for compact states, touch gestures, animations, responsive behavior, and rich content including TreeView and ListView. ## When to Use This Skill - Implementing collapsible navigation menus or sidebars - Creating responsive navigation that adapts to screen size - Building expandable panels with icon-only docked states - Adding gesture-based sidebar toggle on touch devices - Positioning sidebars in various directions (left, right, top, bottom) - Implementing backdrop overlays to focus on sidebar content - Creating multi-level navigation with TreeView or ListView - Managing sidebar visibility with auto-close behavior - Building toggle buttons with show(), hide(), toggle() methods - Applying animations and RTL support to sidebars ## Documentation and Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) - Angular CLI setup and project initialization (Recommended) - Installing Syncfusion packages (Ivy and ngcc versions) - Importing modules and CSS styles - Creating basic sidebar component - ViewChild setup and initialization ### SystemJS Setup (Alternative) 📄 **Read:** [references/systemjs-setup.md](references/systemjs-setup.md) - SystemJS configuration and installation - systemjs.config.js setup with Syncfusion mappings - UMD bundle configuration - Creating Sidebar with SystemJS - Development server and running the application - SystemJS vs Angular CLI comparison ### Sidebar Positioning and Behavior 📄 **Read:** [references/sidebar-positioning.md](references/sidebar-positioning.md) - Sidebar types: Push, Slide, Over, Auto - Positioning: Left, Right, Top, Bottom - Fixed positioning for static sidebars - Docking with enableDock and dockSize properties - Multiple sidebars on same page - dataBind() for dynamic property updates ### Sidebar Interactions and Control 📄 **Read:** [references/sidebar-interactions.md](references/sidebar-interactions.md) - Control methods: show(), hide(), toggle() - Auto-close with mediaQuery for responsive behavior - closeOnDocumentClick for external click handling - Backdrop overlay with showBackdrop - Touch gesture support with enableGestures - Open and close event handling ### Sidebar Content and Components 📄 **Read:** [references/sidebar-content.md](references/sidebar-content.md) - ListView integration for list-based content - TreeView integration for hierarchical menus - Custom HTML content and menu items - Target element configuration - Content structure and layout patterns ### Animations and Styling 📄 **Read:** [references/animations-and-styles.md](references/animations-and-styles.md) - Animation control with animate property - Animation types and variations - CSS theming with Material3 and other themes - RTL (right-to-left) support with enableRtl - Responsive design patterns - CRG (Custom Resource Generator) usage ### Advanced Features and Patterns 📄 **Read:** [references/advanced-features.md](references/advanced-features.md) - Persistence with enablePersistence - RTL implementation details - Accessibility features - Hiding sidebars with routing - Performance optimization - Edge cases and troubleshooting ## Quick Start Example ```typescript import { SidebarModule } from '@syncfusion/ej2-angular-navigations'; import { Component, ViewChild } from '@angular/core'; import { SidebarComponent } from '@syncfusion/ej2-angular-navigations'; @Component({ imports: [SidebarModule], standalone: true, selector: 'app-root', template: `<ejs-sidebar #sidebar id="default-sidebar"> <div class="title">Sidebar Content</div> </ejs-sidebar> <div> <div class="title">Main Content</div> <button (click)="toggleSidebar()">Toggle Sidebar</button> </div>`, styles: [` .title { padding: 20px; font-weight: bold; } `] }) export class AppComponent { @ViewChild('sidebar') sidebar?: SidebarComponent; toggleSidebar() { this.sidebar?.toggle(); } } ``` ## Target Property Behavior The sidebar's `target` property controls which element is affected when the sidebar expands/collapses. There are **two distinct modes**: ### Implicit Targeting (Recommended - Default Behavior) **No `target` property is specified.** The sidebar automatically targets the **next sibling `<div>`** element: ```typescript <ejs-sidebar id="sidebar" type="Push"></ejs-sidebar> <div> <!-- Automatically becomes target - no wrapper needed --> <div class="content">Main Content</div> </div> ``` ✅ **Advantages:** - Simple and clean code - No wrapper element needed - Perfect for straightforward layouts - **Use this for most applications** --- ### Explicit Targeting (Advanced - When You Need Control) Use the **`[target]="'#selector'"`** property to explicitly specify which element to affect: ```typescript <ejs-sidebar [target]="'#content-area'" type="Push"></ejs-sidebar> <div id="content-area"> <!-- Explicit target --> <div> <!-- ⚠️ REQUIRED: Inner wrapper --> <div class="content">Main Content</div> </div> </div> ``` ⚠️ **IMPORTANT:** When using explicit `target`, you **MUST include an inner wrapper `<div>`** inside the target container for CSS transforms to work correctly. **Use explicit targeting when:** - You want to exclude certain elements (header, footer) from sidebar effects - You have complex layouts with multiple sections - You need fine-grained control over transformation --- ### When to Use Each Mode | Mode | When to Use | Complexity | Wrapper Needed | |------|-------------|-----------|-----------------| | **Implicit** (No target) | Default for most layouts | Simple | ❌ No | | **Explicit** (With target) | Complex layouts, selective targeting | Advanced | ✅ Yes (inner) | **See detailed examples in [references/sidebar-positioning.md](references/sidebar-positioning.md#target-property---when-and-how-to-use)** --- ## API Properties Reference The Sidebar component exposes the following properties to control its behavior and appearance: ### animate **Type:** `boolean` | **Default:** `true` Enable or disable animation transitions when expanding or collapsing the sidebar. ```typescript // Example: Disable animations for instant toggle <ejs-sidebar [animate]="false"></ejs-sidebar> // Example: Enable animations (default) <ejs-sidebar [animate]="true"></ejs-sidebar> ``` --- ### closeOnDocumentClick **Type:** `boolean` | **Default:** `false` Specifies whether the sidebar closes when clicking outside of it on the main content area. ```typescript // Example: Auto-close sidebar on document click <ejs-sidebar [closeOnDocumentClick]="true"></ejs-sidebar> // Example: In component this.closeOnClick = true; ``` --- ### dockSize **Type:** `string | number` | **Default:** `'auto'` Specifies the width of the sidebar when in dock state (collapsed but still visible with icons). ```typescript // Example: Set dock size to 72 pixels <ejs-sidebar [dockSize]="'72px'" [enableDock]="true"></ejs-sidebar> // Example: Set as number <ejs-sidebar [dockSize]="72" [enableDock]="true"></ejs-sidebar> // Example: In component public dockSize: string = '72px'; ``` --- ### enableDock **Type:** `boolean` | **Default:** `false` Enables the docking state where sidebar shows icons only and expands on hover or click. ```typescript // Example: Enable docking for icon-only sidebar <ejs-sidebar [enableDock]="true" [dockSize]="'72px'"> <div class="sidebar-item" title="Home"> <i class="e-icons e-home"></i> </div> <div class="sidebar-item" title="Settings"> <i class="e-icons e-settings"></i> </div> </ejs-sidebar> // Example: In component public enableDock = true; public dockSize = '72px'; ``` --- ### enableGestures **Type:** `boolean` | **Default:** `true` Enables touch gestures (swipe) to open/close the sidebar on touch devices. ```typescript // Example: Enable gesture support (default) <ejs-sidebar [enableGestures]="true"></ejs-sidebar> // Example: Disable gestures for specific use cases <ejs-sidebar [enableGestures]="false"></ejs-sidebar> ``` --- ### enablePersistence **Type:** `boolean` | **Default:** `false` Enable persisting the sidebar state (open/closed, position, type) between page reloads using localStorage. ```typescript // Example: Enable persistence to remember sidebar state <ejs-sidebar [enablePersistence]="true"></ejs-sidebar> // Persisted states: // 1. Position (Left/Right) // 2. Type (Push/Slide/Over/Auto) // 3. Open/Closed state ``` --- ### enableRtl **Type:** `boolean` | **Default:** `false` Specifies right-to-left layout for the sidebar, useful for RTL languages like Arabic and Hebrew. ```typescript // Example: Enable RTL layout <ejs-sidebar [enableRtl]="true"></ejs-sidebar> // Example: Dynamically set based on language public isRtl = document.documentElement.lang === 'ar'; <ejs-sidebar [enableRtl]="isRtl"></ejs-sidebar> ``` --- ### isOpen **Type:** `boolean` | **Default:** `false` Gets or sets whether the sidebar is in open (expanded) or closed (collapsed) state. ```typescript // Example: Initially open sidebar <ejs-sidebar [isOpen]="true"></ejs-sidebar> // Example: Initially closed (default) <ejs-sidebar [isOpen]="false"></ejs-sidebar> // Example: Toggle state from component @ViewChild('sidebar') sidebar?: SidebarComponent; toggleOpen() { this.sidebar!.isOpen = !this.sidebar!.isOpen; } // Note: When sidebar type is 'Auto', this property is ignored on mobile devices ``` --- ### mediaQuery **Type:** `string | MediaQueryList` | **Default:** `null` Specifies a media query string that automatically opens the sidebar when the query matches. ```typescript // Example: Open sidebar on screens wider than 600px <ejs-sidebar [mediaQuery]="'(min-width: 600px)'"></ejs-sidebar> // Example: Using MediaQueryList object public mediaQuery = window.matchMedia('(min-width: 768px)'); <ejs-sidebar [mediaQuery]="mediaQuery"></ejs-sidebar> // Example: Common breakpoints // Mobile: '(max-width: 600px)' // Tablet: '(min-width: 601px) and (max-width: 1024px)' // Desktop: '(min-width: 1025px)' ``` --- ### position **Type:** `SidebarPosition` | **Default:** `'Left'` Specifies the position of the sidebar: `'Left'` or `'Right'`. ```typescript // Example: Position sidebar on the left (default) <ejs-sidebar [position]="'Left'"></ejs-sidebar> // Example: Position sidebar on the right <ejs-sidebar [position]="'Right'"></ejs-sidebar> // Example: Set position dynamically public sidebarPosition: SidebarPosition = 'Left'; <ejs-sidebar [position]="sidebarPosition"></ejs-sidebar> ``` Available values: - `'Left'` - Sidebar appears on the left side - `'Right'` - Sidebar appears on the right side --- ### showBackdrop **Type:** `boolean` | **Default:** `false` Specifies whether to display an overlay backdrop on the main content when sidebar is open. ```typescript // Example: Show backdrop overlay <ejs-sidebar [showBackdrop]="true"></ejs-sidebar> // Example: Backdrop with auto-close on click <ejs-sidebar [showBackdrop]="true" [closeOnDocumentClick]="true"></ejs-sidebar> // Example: Combine with other properties <ejs-sidebar [showBackdrop]="true" [closeOnDocumentClick]="true" [type]="'Over'"> </ejs-sidebar> ``` --- ### target