|
| 1 | +--- |
| 2 | +title: {Platform} Splitter Component | Layout Controls | Infragistics |
| 3 | +_description: Use the {ProductName} Splitter component to create two resizable panes with horizontal or vertical layouts, collapse and expand behavior, keyboard support, and nested split views. |
| 4 | +_keywords: splitter, split panes, resizable panes, web components splitter, {Platform} splitter, {ProductName} |
| 5 | +_license: MIT |
| 6 | +mentionedTypes: ["Splitter"] |
| 7 | +--- |
| 8 | + |
| 9 | +# {Platform} Splitter Overview |
| 10 | + |
| 11 | +The {ProductName} Splitter provides a resizable split-pane layout that divides content into two areas: `start` and `end`. Users can drag the splitter bar, use keyboard shortcuts, or collapse and expand panes with built-in controls. You can also nest splitters to build complex dashboard-style layouts. |
| 12 | + |
| 13 | +## {Platform} Splitter Example |
| 14 | + |
| 15 | +`sample="/layouts/splitter/base", height="520", alt="{Platform} Splitter Example"` |
| 16 | + |
| 17 | +<div class="divider--half"></div> |
| 18 | + |
| 19 | +## Usage |
| 20 | + |
| 21 | +First, you need to install the {ProductName} by running the following command: |
| 22 | + |
| 23 | +```cmd |
| 24 | +npm install {PackageWebComponents} |
| 25 | +``` |
| 26 | + |
| 27 | +Before using the `Splitter`, you need to register it as follows: |
| 28 | + |
| 29 | +```ts |
| 30 | +import { defineComponents, IgcSplitterComponent } from 'igniteui-webcomponents'; |
| 31 | + |
| 32 | +defineComponents(IgcSplitterComponent); |
| 33 | +``` |
| 34 | + |
| 35 | +For a complete introduction to the {ProductName}, read the [**Getting Started**](../general-getting-started.md) topic. |
| 36 | + |
| 37 | +Use the `start` and `end` slots to place pane content: |
| 38 | + |
| 39 | +```html |
| 40 | +<igc-splitter style="height: 400px;"> |
| 41 | + <div slot="start">Start pane content</div> |
| 42 | + <div slot="end">End pane content</div> |
| 43 | +</igc-splitter> |
| 44 | +``` |
| 45 | + |
| 46 | +### Orientation |
| 47 | + |
| 48 | +Set the `orientation` property to control pane direction: |
| 49 | + |
| 50 | +- `horizontal` (default): start and end panes are rendered left and right. |
| 51 | +- `vertical`: start and end panes are rendered top and bottom. |
| 52 | + |
| 53 | +```html |
| 54 | +<igc-splitter orientation="vertical" style="height: 400px;"> |
| 55 | + <div slot="start">Top pane</div> |
| 56 | + <div slot="end">Bottom pane</div> |
| 57 | +</igc-splitter> |
| 58 | +``` |
| 59 | + |
| 60 | +### Pane Size and Constraints |
| 61 | + |
| 62 | +Use size properties to set initial and constrained pane sizes: |
| 63 | + |
| 64 | +- `start-size`, `end-size` |
| 65 | +- `start-min-size`, `end-min-size` |
| 66 | +- `start-max-size`, `end-max-size` |
| 67 | + |
| 68 | +Values accept CSS length values such as `px` and `%`. |
| 69 | + |
| 70 | +```html |
| 71 | +<igc-splitter |
| 72 | + start-size="35%" |
| 73 | + end-size="65%" |
| 74 | + start-min-size="200px" |
| 75 | + end-min-size="180px" |
| 76 | + style="height: 420px;" |
| 77 | +> |
| 78 | + <div slot="start">Navigation</div> |
| 79 | + <div slot="end">Main content</div> |
| 80 | +</igc-splitter> |
| 81 | +``` |
| 82 | + |
| 83 | +### Collapsing and Resizing |
| 84 | + |
| 85 | +Use these properties to control interactions: |
| 86 | + |
| 87 | +- `disable-resize`: disables pane resizing. |
| 88 | +- `disable-collapse`: disables pane collapsing. |
| 89 | +- `hide-drag-handle`: hides the drag handle. |
| 90 | +- `hide-collapse-buttons`: hides collapse and expand buttons. |
| 91 | + |
| 92 | +You can also collapse or expand panes programmatically: |
| 93 | + |
| 94 | +```ts |
| 95 | +const splitter = document.querySelector('igc-splitter') as IgcSplitterComponent; |
| 96 | + |
| 97 | +splitter.toggle('start'); // collapse start pane |
| 98 | +splitter.toggle('start'); // expand start pane |
| 99 | +``` |
| 100 | + |
| 101 | +### Nested Splitters |
| 102 | + |
| 103 | +Splitters can be nested to create multi-region layouts. |
| 104 | + |
| 105 | +`sample="/layouts/splitter/nested", height="520", alt="{Platform} Nested Splitter Example"` |
| 106 | + |
| 107 | +## Events |
| 108 | + |
| 109 | +The Splitter emits the following events during resize operations: |
| 110 | + |
| 111 | +- `igcResizeStart`: fired once when resizing starts. |
| 112 | +- `igcResizing`: fired continuously while resizing. |
| 113 | +- `igcResizeEnd`: fired once when resizing ends. |
| 114 | + |
| 115 | +The event detail includes current `startPanelSize`, `endPanelSize`, and `delta` for ongoing and end events. |
| 116 | + |
| 117 | +```ts |
| 118 | +const splitter = document.querySelector('igc-splitter'); |
| 119 | + |
| 120 | +splitter?.addEventListener('igcResizeEnd', (event: CustomEvent) => { |
| 121 | + console.log(event.detail.startPanelSize, event.detail.endPanelSize, event.detail.delta); |
| 122 | +}); |
| 123 | +``` |
| 124 | + |
| 125 | +## Keyboard Navigation |
| 126 | + |
| 127 | +When the splitter bar is focused: |
| 128 | + |
| 129 | +| Keys | Description | |
| 130 | +| ---- | ----------- | |
| 131 | +| <kbd>Arrow Left</kbd> / <kbd>Arrow Right</kbd> | Resize panes in horizontal orientation | |
| 132 | +| <kbd>Arrow Up</kbd> / <kbd>Arrow Down</kbd> | Resize panes in vertical orientation | |
| 133 | +| <kbd>Home</kbd> | Snap start pane to its minimum size | |
| 134 | +| <kbd>End</kbd> | Snap start pane to its maximum size | |
| 135 | +| <kbd>Ctrl</kbd> + <kbd>Arrow Left</kbd> / <kbd>Arrow Up</kbd> | Collapse or expand the start pane | |
| 136 | +| <kbd>Ctrl</kbd> + <kbd>Arrow Right</kbd> / <kbd>Arrow Down</kbd> | Collapse or expand the end pane | |
| 137 | + |
| 138 | +## Styling |
| 139 | + |
| 140 | +The `Splitter` component exposes CSS parts for styling: |
| 141 | + |
| 142 | +| Name | Description | |
| 143 | +| ---- | ----------- | |
| 144 | +| `splitter-bar` | The draggable separator between panes | |
| 145 | +| `drag-handle` | The drag handle element in the splitter bar | |
| 146 | +| `start-pane` | The start pane container | |
| 147 | +| `end-pane` | The end pane container | |
| 148 | +| `start-collapse-btn` | Button that collapses the start pane | |
| 149 | +| `end-collapse-btn` | Button that collapses the end pane | |
| 150 | +| `start-expand-btn` | Button that expands the start pane | |
| 151 | +| `end-expand-btn` | Button that expands the end pane | |
| 152 | + |
| 153 | +It also supports theme CSS variables, including: |
| 154 | + |
| 155 | +- `--bar-color` |
| 156 | +- `--handle-color` |
| 157 | +- `--expander-color` |
| 158 | +- `--bar-color-active` |
| 159 | +- `--handle-color-active` |
| 160 | +- `--expander-color-active` |
| 161 | +- `--focus-color` |
| 162 | +- `--size` |
| 163 | + |
| 164 | +```css |
| 165 | +igc-splitter { |
| 166 | + --bar-color: #011627; |
| 167 | + --handle-color: #ecaa53; |
| 168 | + --expander-color: #ecaa53; |
| 169 | + --bar-color-active: #011627; |
| 170 | + --handle-color-active: #ecaa53; |
| 171 | + --expander-color-active: #ecaa53; |
| 172 | + --focus-color: #ecaa53; |
| 173 | +} |
| 174 | +``` |
| 175 | + |
| 176 | +`sample="/layouts/splitter/styling", height="520", alt="{Platform} Splitter Styling Example"` |
| 177 | + |
| 178 | +## API References |
| 179 | + |
| 180 | +- `Splitter` |
| 181 | +- [`Styling & Themes`](../themes/overview.md) |
| 182 | + |
| 183 | +## Additional Resources |
| 184 | + |
| 185 | +- [{ProductName} **Forums**]({ForumsLink}) |
| 186 | +- [{ProductName} **GitHub**]({GithubLink}) |
0 commit comments