split.js

library1.6.5jsnpmunverified

Split.js is a lightweight, 2kb gzipped utility for creating resizeable split views in web applications. It is currently stable at version 1.6.5 and maintains a consistent release cadence with minor bug fixes and feature enhancements, as seen in recent 1.5.x releases. Key differentiators include its zero-dependency footprint, small size, and high performance due to its pure CSS resizing approach without attaching window event listeners. It is unopinionated, working well with various layout models like `float` and `flex`, and boasts broad browser compatibility, supporting IE9 and early versions of modern browsers. It provides a simple API to create and manage split panels, allowing developers to control initial sizes, minimum/maximum sizes, gutter behavior, and drag intervals.

web-framework

npm install split.js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPLIT.JS

split.js

web-frameworkjavascriptv1.6.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Split

✓ import Split from 'split.js'

✗ const Split = require('split.js')

While CommonJS `require` is supported, ES Modules (`import`) are the preferred and modern approach for bundling.

Split types

✓ import type { SplitInstance, Options } from 'split.js'

For TypeScript projects, these types can be imported to enhance type safety for the Split instance and configuration options.

UMD Global

✓ <script src="https://unpkg.com/split.js/dist/split.min.js"></script>

When included via a script tag, Split.js makes the `Split` function available globally on the `window` object.

This quickstart demonstrates how to create a basic horizontal split view with three resizeable panels using Split.js, including initial sizing, minimum panel sizes, custom gutter styling, and event handlers for drag actions. It showcases typical setup for a modern web application using ES Modules.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Split.js Quickstart</title> <style> #split-container { display: flex; /* Use flexbox for horizontal split */ height: 300px; border: 1px solid #ccc; overflow: hidden; } .split-panel { background-color: #f0f0f0; padding: 15px; overflow: auto; flex-grow: 1; /* Allows panels to grow/shrink with split.js */ } .gutter { background-color: #eee; background-repeat: no-repeat; background-position: 50%; cursor: col-resize; /* Default for horizontal splits */ } .gutter.gutter-horizontal { background-image: url('data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAxCAYAAAB2M2UfAAAAABmJLR0QA/wD/AP+Ad/gAAAAwSURBVDjLYwCCDQgGAgEC/j+P/n/8A4gBCAB+0M2KBAmDAAGg9QYAAAEhB0oBAAEGAAAAAElFTkSuQmCC'); } </style> </head> <body> <div id="split-container"> <div id="panel-a" class="split-panel">Panel A</div> <div id="panel-b" class="split-panel">Panel B</div> <div id="panel-c" class="split-panel">Panel C</div> </div> <script type="module"> import Split from 'split.js'; document.addEventListener('DOMContentLoaded', () => { const split = Split(['#panel-a', '#panel-b', '#panel-c'], { sizes: [33, 33, 34], // Initial sizes in percentage minSize: 100, // Minimum size for each panel in pixels gutterSize: 8, // Size of the gutter in pixels cursor: 'col-resize', // Cursor to show when dragging (for horizontal) onDrag: (sizes) => { // console.log('Current sizes:', sizes); }, onDragEnd: (sizes) => { // console.log('Final sizes:', sizes); } }); // To dynamically change sizes (e.g., after an event) // setTimeout(() => { // split.setSizes([20, 50, 30]); // }, 3000); // To destroy the split instance // setTimeout(() => { // split.destroy(); // }, 6000); }); </script> </body> </html>

Debug

Known issues

breakingIn Split.js v1.5.0, the behavior for collapsing elements changed. Instead of setting the element's width to `0`, collapsing now defaults to using the `minSize` option. This might break layouts that previously relied on a `0` width after collapse.

fix

Review existing code that relies on elements collapsing to zero width. Adjust `minSize` or implement custom logic within `elementStyle` to achieve a zero-width collapse if desired, or ensure your layout can gracefully handle elements collapsing to `minSize`.

affects: >=1.5.0

gotchaPrior to v1.5.7, passing very low `sizes` values (e.g., `0`) to `Split()` or `setSizes()` that computed to less than the `gutterSize` could break the layout.

fix

Upgrade to Split.js v1.5.7 or later to resolve this issue. If upgrading is not possible, ensure that all `sizes` values are sufficiently large to accommodate the `gutterSize` and `minSize` constraints.

affects: <1.5.7

gotchaVersions prior to v1.5.9 had issues with split views that were initially hidden (e.g., via `display: none;` on the container). These views would often not initialize or render correctly when they became visible.

fix

Update to Split.js v1.5.9 or newer. If stuck on an older version, consider initializing Split.js only after the container becomes visible, or use a workaround like calling `split.setSizes()` once the container is displayed.

affects: <1.5.9

gotchaAs of v1.5.1, dragging can only be initiated with the left mouse button. If users try to drag with other mouse buttons (e.g., right-click or middle-click), the split view will not respond.

fix

This is intended behavior for most common UI patterns. Ensure users are aware that only the left mouse button should be used for dragging splitters. No code fix is typically required unless custom behavior for other mouse buttons is desired (which would require overriding Split.js's default event handling).

affects: >=1.5.1

Errors

Common errors & fixes

Split.js: Element with selector '#non-existent-id' not found.

The selector(s) passed to the Split.js constructor do not match any elements currently in the DOM.

fix

Ensure that the HTML elements you intend to split exist in the DOM when `Split()` is called and that their IDs or class names correctly match the selectors provided in the array (e.g., `Split(['#panel1', '#panel2'])`).

Split gutter jumps or behaves erratically during dragging.

This was a known bug in older versions of Split.js where the gutter's position could become inconsistent during a drag operation, particularly when quickly moving the mouse.

fix

Upgrade to Split.js v1.5.4 or newer, which includes a fix to prevent the gutter from jumping when dragging. Also, ensure your CSS for the `.gutter` elements properly defines its sizing and positioning.

Layout breaks or panels disappear when initial `sizes` are very small, or when `minSize` is greater than the calculated percentage size.

Before v1.5.7, very small initial `sizes` values could lead to layout issues, especially if they calculated to less than the `gutterSize`. Also, if `minSize` for a panel is too large relative to the available space or its `size` percentage, it can cause panels to overlap or disappear.

fix

Update to Split.js v1.5.7+. Always ensure that your `sizes` array, when converted to pixel values, respects the `minSize` and `gutterSize` constraints. If a panel's calculated size would be less than its `minSize`, Split.js will adjust, but extreme values can lead to unexpected behavior. The `expandToMin` option (v1.5.0+) can help grow initial sizes to meet `minSize`.

Upgrade

Version history

1.6.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/nathancahill/split ↗

packagehttps://www.npmjs.com/package/split.js ↗

homepagehttps://split.js.org/ ↗