| `snapOffset` | Number | `30` | Snap to minimum size offset in pixels. |
| `dragInterval` | Number | `1` | Number of pixels to drag. |
| `direction` | String | `'horizontal'` | Direction to split: horizontal or vertical. |
| `cursor` | String | `'col-resize'` | Cursor to display while dragging. |
| `gutter` | Function | | Called to create each gutter element |
| `elementStyle` | Function | | Called to set the style of each element. |
| `gutterStyle` | Function | | Called to set the style of the gutter. |
| `onDrag` | Function | | Callback on drag. |
| `onDragStart` | Function | | Callback on drag start. |
| `onDragEnd` | Function | | Callback on drag end. |
## Important Note
Split.js does not set CSS beyond the minimum needed to manage the width or height of the elements.
This is by design. It makes Split.js flexible and useful in many different situations.
If you create a horizontal split, you are responsible for (likely) floating the elements and the gutter,
and setting their heights. See the [CSS](#css) section below. If your gutters are not showing up, check the applied CSS styles.
**THIS IS THE #1 QUESTION ABOUT THE LIBRARY**.
## Options
#### sizes
An array of initial sizes of the elements, specified as percentage values. Example: Setting the initial sizes to `25%` and `75%`.
```js
Split(['#one', '#two'], {
sizes: [25, 75],
})
```
#### minSize. Default: `100`
An array of minimum sizes of the elements, specified as pixel values. Example: Setting the minimum sizes to `100px` and `300px`, respectively.
```js
Split(['#one', '#two'], {
minSize: [100, 300],
})
```
If a number is passed instead of an array, all elements are set to the same minimum size:
```js
Split(['#one', '#two'], {
minSize: 100,
})
```
#### expandToMin. Default: `false`
When the split is created, if `expandToMin` is `true`, the minSize for each element overrides the percentage value from the `sizes` option.
Example: The first element (`#one`) is set to 25% width of the parent container. However, it's `minSize` is `300px`. Using `expandToMin: true` means that
the first element will always load at at least `300px`, even if `25%` were smaller.
```js
Split(['#one', '#two'], {
sizes: [25, 75],
minSize: [300, 100],
expanedToMin: true,
})
```
#### gutterSize. Default: `10`
Gutter size in pixels. Example: Setting the gutter size to `20px`.
```js
Split(['#one', '#two'], {
gutterSize: 20,
})
```
#### gutterAlign. Default: `'center'`
Possible options are `'start'`, `'end'` and `'center'`. Determines how the gutter aligns between the two elements.
`'start'` shrinks the first element to fit the gutter, `'end'` shrinks the second element to fit the gutter and `'center'` shrinks both
elements by the same amount so the gutter sits between. Added in v1.5.3.
Example: move gutter to the side of the second element:
```js
Split(['#one', '#two'], {
gutterAlign: 'end',
})
```
#### snapOffset. Default: `30`
Snap to minimum size at this offset in pixels. Example: Set to `0` to disable to snap effect.
```js
Split(['#one', '#two'], {
snapOffset: 0,
})
```
#### dragInterval. Default: `1`
Drag this number of pixels at a time. Defaults to `1` for smooth dragging, but can be set to a pixel value to
give more control over the resulting sizes. Works particularly well when the `gutterSize` is set to the same size.
Added in v1.5.3. Example: Drag 20px at a time:
```js
Split(['#one', '#two'], {
dragInterval: 20,
})
```
#### direction. Default: `'horizontal'`
Direction to split in. Can be `'vertical'` or `'horizontal'`. Determines which CSS properties are applied (ie. width/height) to each element and gutter. Example: split vertically:
```js
Split(['#one', '#two'], {
direction: 'vertical',
})
```
#### cursor. Default: `'col-resize'`
Cursor to show on the gutter (also applied to the body on dragging to prevent flickering). Defaults to `'col-resize'`for `direction: 'horizontal'` and `'row-resize'` for `direction: 'vertical'`:
```js
Split(['#one', '#two'], {
direction: 'vertical',
cursor: 'row-resize',
})
```
#### gutter
Optional function called to create each gutter element. The signature looks like this:
```js
;(index, direction, pairElement) => HTMLElement
```
Defaults to creating a `div` with `class="gutter gutter-horizontal"` or `class="gutter gutter-vertical"`, depending on the direction. The default gutter function looks like this:
```js
;(index, direction) => {
const gutter = document.createElement('div')
gutter.className = `gutter gutter-${direction}`
return gutter
}
```
The returned element is then inserted into the DOM, and it's width or height are set. This option can be used to clone an existing DOM element, or to create a new element with custom styles.
Returning a falsey value like `null` or `false` will not insert a gutter. This behavior was added in v1.4.1.
An additional argument, `pairElement`, is passed to the gutter function: this is the DOM element after (to the right or below) the gutter. This argument was added in v1.4.1.
This final argument makes it easy to return the gutter that has already been created, for example, if `split.destroy()` was called with the option to preserve the gutters.
Dimension will be a string, `'width'` or `'height'`, and can be used in the return style. `elementSize` is the target percentage value of the element, and `gutterSize` is the target pixel value of the gutter.
It should return an object with CSS properties to apply to the element. For horizontal splits, the return object looks like this:
Optional function called when setting the CSS style of the gutters. The signature looks like this:
```js
;(dimension, gutterSize, index) => Object
```
Dimension is a string, either `'width'` or `'height'`, and `gutterSize` is a pixel value representing the width of the gutter.
It should return a similar object as `elementStyle`, an object with CSS properties to apply to the gutter. Since gutters have fixed widths, it will generally look like this:
```js
{
'width': '10px'
}
```
Both `elementStyle` and `gutterStyle` are called continously while dragging, so don't do anything besides return the style object in these functions. Both of these functions should be _pure_, returning the same values for the same inputs and not modifying any external state.
#### onDrag, onDragStart, onDragEnd
Callbacks that can be added on drag (fired continously), drag start and drag end. If doing more than basic operations in `onDrag`, add a debounce function to rate limit the callback.
`onDragStart` and `onDragEnd` are passed the initial and final sizes of the split since it's a common pattern to access the sizes this way.
Their function signature looks like this, where `sizes` is an array of percentage values like returned by `getSizes()`:
```js
sizes => {}
```
## Usage Examples
Reference HTML for examples. Gutters are inserted automatically:
```html
<div>
<div id="one">content one</div>
<div id="two">content two</div>
<div id="three">content three</div>
</div>
```
A split with two elements, starting at `25%` and `75%` wide, with `200px` minimum width.
```js
Split(['#one', '#two'], {
sizes: [25, 75],
minSize: 200,
})
```
A split with three elements, starting with even (default) widths and minimum widths set to `100px`, `100px` and `300px`, respectively.
Split.js returns an instance with a couple of functions. The instance is returned on creation:
```js
var instance = Split([], ...)
```
#### `.setSizes([])`
setSizes behaves the same as the `sizes` configuration option, passing an array of percentages. It updates the sizes of the elements in the split. Added in v1.1.0:
```js
instance.setSizes([25, 75])
```
#### `.getSizes()`
getSizes returns an array of percents, suitable for using with `setSizes` or creation. Not supported in IE8. Added in v1.1.2:
```js
instance.getSizes() > [25, 75]
```
#### `.collapse(index)`
collapse changes the size of element at `index` to it's `minSize`. Every element except the last is collapsed towards the front (left or top). The last is collapsed towards the back. Not supported in IE8. Added in v1.1.0:
Destroy the instance. It removes the gutter elements, and the size CSS styles Split.js set. Added in v1.1.1.
Passing `preserveStyles = true` does not remove the CSS styles. Option added in v1.4.0.
Passing `preserveGutters = true` does not remove the gutter elements. Option added in v1.4.1.
```js
instance.destroy()
```
## CSS
In being non-opionionated, the only CSS Split.js sets is the widths or heights of the elements. Everything else is left up to you. You must set the elements and gutter heights when using horizontal mode. The gutters will not be visible if their height is 0px. Here's some basic CSS to style the gutters with, although it's not required. Both grip images are included in this repo:
```css
.gutter {
background-color: #eee;
background-repeat: no-repeat;
background-position: 50%;
}
.gutter.gutter-horizontal {
background-image: url('grips/vertical.png');
cursor: col-resize;
}
.gutter.gutter-vertical {
background-image: url('grips/horizontal.png');
cursor: row-resize;
}
```
The grip images are small files and can be included with base64 instead:
Split.js also works best when the elements are sized using `border-box`. The `split` class would have to be added manually to apply these styles:
```css
.split {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
}
```
And for horizontal splits, make sure the layout allows elements (including gutters) to be displayed side-by-side. Floating the elements is one option:
```css
.split,
.gutter.gutter-horizontal {
float: left;
}
```
If you use floats, set the height of the elements including the gutters. The gutters will not be visible otherwise if the height is set to 0px.
```css
.split,
.gutter.gutter-horizontal {
height: 300px;
}
```
Overflow can be handled as well, to get scrolling within the elements:
```css
.split {
overflow-y: auto;
overflow-x: hidden;
}
```
## Browser Support
This library uses [CSS calc()](https://developer.mozilla.org/en-US/docs/Web/CSS/calc#AutoCompatibilityTable), [CSS box-sizing](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing#AutoCompatibilityTable) and [JS getBoundingClientRect()](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect#AutoCompatibilityTable). These features are supported in the following browsers:
Gracefully falls back in IE 8 and below to only setting the initial widths/heights and not allowing dragging. IE 8 requires polyfills for `Array.isArray()`, `Array.forEach`, `Array.map`, `Array.filter`, `Object.keys()` and `getComputedStyle`. This script from [Polyfill.io](https://polyfill.io/) includes all of these, adding 1.91 kb to the gzipped size.
This is **ONLY NEEDED** if you are supporting **IE8:**
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/splitjs#sponsor)]
