syncfusion-angular-sidebar

What this skill does

# 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-si