syncfusion-javascript-splitter

# Implementing Syncfusion TypeScript Splitter The Syncfusion Splitter control enables you to create complex, responsive multi-pane layouts in web applications. It provides built-in resizing, collapse/expand functionality, comprehensive event handling, and support for nested panes with full programmatic control. ## When to Use This Skill - **Setting up a Splitter:** Initial configuration, dependency installation, basic initialization - **Configuring panes:** Sizing (pixels/percentages), fixed vs flexible panes, min/max constraints - **Orientation:** Horizontal vs vertical layouts - **Interactive features:** Collapse/expand panes, programmatic control, dynamic pane management - **Content:** Loading HTML markup, text content, or dynamic content - **Resizing:** Configuring resize behavior, preventing resize, handling resize events - **Styling:** Customizing split bars, resize handles, arrows, colors - **Complex layouts:** Nested splitters, code editor layouts, multi-level pane hierarchies - **Internationalization:** Right-to-left (RTL) support for Arabic, Hebrew, and other RTL languages - **Event Handling:** Working with all Splitter events (before/after expand/collapse, resize, creation) - **API Methods:** Programmatically manipulating splitter state (add/remove panes, expand/collapse, refresh) - **Advanced Configuration:** Persistence, sanitization, pane reordering, locale management --- ## Splitter Overview & Key Capabilities The Splitter is a flexible layout component that: - Divides containers into **multiple panes** separated by resizable bars - Supports **horizontal** (default) and **vertical** orientations - Enables **collapsible panes** with expand/collapse icons - Allows **flexible sizing** in pixels or percentages - Supports **min/max constraints** during resizing - Provides **nested splitters** for complex layouts - Includes **built-in styling** customization via CSS - Supports **RTL** for right-to-left languages - Automatically adjusts panes using **flex layout** --- ## Documentation and Navigation Guide ### API REFERENCE (Complete) **[Complete API Reference](#complete-api-reference)** — This document Comprehensive documentation of ALL components: - **Splitter Properties** - All 12 properties with code examples - **Pane Properties** - All 8 pane configuration properties - **Methods** - All 12 methods with parameters and return types (addEventListener, addPane, appendTo, collapse, dataBind, destroy, expand, getRootElement, refresh, removeEventListener, removePane, Inject) - **Events** - All 9 events with argument documentation (created, beforeExpand, expanded, beforeCollapse, collapsed, resizeStart, resizing, resizeStop, beforeSanitizeHtml) - **Event Arguments** - Full documentation of all event argument properties ### Getting Started **[references/getting-started.md](references/getting-started.md)** - Package dependencies (@syncfusion/ej2-layouts) - npm installation and setup - CSS imports (fluent2.css theme) - Basic Splitter component initialization - HTML markup and DOM structure - Creating panes with child elements ### Core Concepts: Panes and Orientation **[references/split-panes-orientation.md](references/split-panes-orientation.md)** - Horizontal layout (default behavior) - Vertical layout (orientation: 'Vertical' property) - Orientation API usage - Pane separators (vertical for horizontal layout, horizontal for vertical) - Dynamic pane management with addPane() method - Dynamic pane removal with removePane() method - Complete examples of both orientations ### Pane Configuration & Sizing **[references/pane-configuration.md](references/pane-configuration.md)** - Pane sizing in pixel format ('200px', '300px') - Pane sizing in percentage format ('30%', '50%') - Auto-sizing with flex layout - Fixed pane sizes via paneSettings - Minimum constraints (min property) - Maximum constraints (max property) - Flexible last pane behavior ### Expand/Collapse Behavior **[references/collapse-expand.md](references/collapse-expand.md)** - Enabling collapsible panes (collapsible: true) - Built-in expand/collapse icons - User-triggered collapse/expand actions - Programmatic expand() method for specific pane index - Programmatic collapse() method for specific pane index - Specify initial collapsed state (collapsed: true property) - Event handling and callbacks - beforeExpand, expanded, beforeCollapse, collapsed events ### Pane Content Options **[references/pane-content.md](references/pane-content.md)** - HTML markup content in panes - Text content strings - Inner HTML via child elements - Dynamic content property - Loading HTML elements - Practical content examples ### Resizing & Constraints **[references/resizing-behavior.md](references/resizing-behavior.md)** - Resizing enabled by default - Resize gripper functionality - Horizontal vs vertical resizing behavior - Adjacent pane auto-adjustment during resize - Min/Max validation constraints - Preventing resizing (resizable: false) - Resizable property per pane configuration - resizeStart, resizing, resizeStop events ### Styling & Customization **[references/styling-customization.md](references/styling-customization.md)** - Split bar CSS customization (.e-split-bar) - Horizontal split bar styling (.e-split-bar-horizontal) - Vertical split bar styling (.e-split-bar-vertical) - Hover and active state styling - Resize handle customization (.e-resize-handler) - Split bar arrow customization (.e-navigate-arrow) - Color and theme customization ### Complex Layouts & Nesting **[references/layouts-nested.md](references/layouts-nested.md)** - Creating nested splitters - Code editor style layout (horizontal + vertical) - Outer and inner splitter configuration - Step-by-step nesting implementation - Multiple nesting levels - Complex multi-pane hierarchies ### Globalization (RTL) **[references/globalization.md](references/globalization.md)** - Right-to-left (RTL) layout support - enableRtl property configuration - RTL for Arabic, Hebrew, and other languages - Default LTR behavior (enableRtl: false) - RTL styling adjustments --- ## Quick Start Example ```typescript import { Splitter } from '@syncfusion/ej2-layouts'; // Initialize Splitter with horizontal orientation (default) let splitObj: Splitter = new Splitter({ height: '250px', width: '600px', paneSettings: [ { size: '200px', content: 'Pane 1' }, { size: '200px', content: 'Pane 2' }, { size: '200px', content: 'Pane 3' } ] }); // Render to DOM splitObj.appendTo('#splitter'); ``` **HTML:** ```html <div id="splitter"> <div></div> <div></div> <div></div> </div> ``` --- ## Common Patterns ### Pattern 1: Responsive Panes with Min/Max ```typescript let splitObj: Splitter = new Splitter({ height: '300px', width: '100%', paneSettings: [ { size: '30%', min: '20%', max: '50%' }, { size: '40%', min: '30%', max: '60%' }, { size: '30%', min: '20%', max: '50%' } ] }); splitObj.appendTo('#splitter'); ``` ### Pattern 2: Collapsible Panes with Initial State ```typescript let splitObj: Splitter = new Splitter({ height: '300px', paneSettings: [ { collapsible: true, size: '250px', content: 'Sidebar', collapsed: false }, { collapsible: true, size: '250px', content: 'Details', collapsed: true } ] }); splitObj.appendTo('#splitter'); ``` ### Pattern 3: Vertical Split (Stacked) ```typescript let splitObj: Splitter = new Splitter({ height: '400px', orientation: 'Vertical', paneSettings: [ { size: '150px' }, { size: '200px' }, { size: '150px' } ] }); splitObj.appendTo('#splitter'); ``` ### Pattern 4: Nested Splitters (Code Editor Layout) ```typescript // Outer vertical splitter let verticalSplit: Splitter = new Splitter({ height: '400px', orientation: 'Vertical', paneSettings: [ { size: '250px', min: '30%' } ] }); verticalSplit.appendTo('#verticalSplitter'); // Inner horizontal splitter (inside first pane) let horizontalSplit: Splitter = new Splitter({ height: '220px', paneSettings: [ { size: '29%', min: '23%' }, { size: '20%', min: '15%' }, { size: '35%', min: '35%' } ] }); horizontalSplit.appendTo('#horizontalSplitter'); ``` ### Pattern 5: Event Handling - Prevent Collapse ```typescript let splitObj: Splitter = new Splitter({ height: '300px', paneSettings: [ { collapsible: true, size: '250px', content: 'Important Pane' }, { collapsible: true, size: '250px', content: 'Other Pane' } ], beforeCollapse: (args: BeforeExpandEventArgs) => { // Prevent collapse of first pane if (args.index[0] === 0) { args.cancel = true; console.log('First pane cannot be collapsed'); } } }); splitObj.appendTo('#splitter'); ``` ### Pattern 6: Dynamically Add/Remove Panes ```typescript let splitObj: Splitter = new Splitter({ height: '300px', paneSettings: [ { size: '50%', content: 'Pane 1' }, { size: '50%', content: 'Pane 2' } ] }); splitObj.appendTo('#splitter'); // Add a new pane document.getElementById('addBtn').addEventListener('click', () => { splitObj.addPane({ size: '200px', content: 'New Pane' }, 1); }); // Remove a pane document.getElementById('removeBtn').addEventListener('click', () => { splitObj.removePane(1); }); ``` ### Pattern 7: Programmatic Expand/Collapse ```typescript let splitObj: Splitter = new Splitter({ height: '300px', paneSettings: [ { collapsible: true, size: '250px', content: 'Pane 1', collapsed: true }, { collapsible: true, size: '250px', content: 'Pane 2' } ] }); splitObj.appendTo('#splitter'); // Expand pane document.getElementById('expandBtn').addEventListener('click', () => { splitObj.expand(0); }); // Collapse pane document.getElementById('collapseBtn').addEventListener('click', () => { splitObj.collapse(0); }); ``` ### Pattern 8: Track Resize Events ```typescript let splitObj: Splitter = new Splitter({ height: '300px', paneSettings: [ { size: '250px', content: 'Pane 1' }, { size: '250px', content: 'Pane 2' } ], resizeStart: (args: ResizeEventArgs) => { console.log('Resize started on pane:', args.index); }, resizing: (args: ResizingEventArgs) => { console.log('Resizing... New sizes:', args.paneSize); }, resizeStop: (args: ResizingEventArgs) => { console.log('Resize completed. Final sizes:', args.paneSize); } }); splitObj.appendTo('#splitter'); ``` ### Pattern 9: Persistent Splitter State ```typescript let splitObj: Splitter = new Splitter({ height: '300px', enablePersistence: true, // Save state to localStorage paneSettings: [ { size: '250px', content: 'Pane 1' }, { size: '250px', content: 'Pane 2' } ] }); splitObj.appendTo('#splitter'); // State automatically persists across page reloads ``` ### Pattern 10: RTL Support ```typescript let splitObj: Splitter = new Splitter({ height: '300px', enableRtl: true, paneSettings: [ { size: '50%', content: 'محتوى عربي' }, // Arabic content { size: '50%', content: 'תוכן עברי' } // Hebrew content ] }); splitObj.appendTo('#splitter'); ``` ## Complete API Reference For detailed examples of all properties, methods, and events, see the [Complete API Reference](references/api-reference.md). ### Splitter Properties Complete list of all properties available on the Splitter component: | Property | Type | Default | Description | |----------|------|---------|-------------| | `height` | `string` | `'100%'` | Height of the Splitter container | | `width` | `string` | `'100%'` | Width of the Splitter container |