Split.js Quickstart

{"id":12061,"library":"split.js","title":"Split.js","description":"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.","status":"active","version":"1.6.5","language":"javascript","source_language":"en","source_url":"https://github.com/nathancahill/split","tags":["javascript","css","split","flexbox","tiny","split-layout","typescript"],"install":[{"cmd":"npm install split.js","lang":"bash","label":"npm"},{"cmd":"yarn add split.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add split.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` is supported, ES Modules (`import`) are the preferred and modern approach for bundling.","wrong":"const Split = require('split.js')","symbol":"Split","correct":"import Split from 'split.js'"},{"note":"For TypeScript projects, these types can be imported to enhance type safety for the Split instance and configuration options.","symbol":"Split types","correct":"import type { SplitInstance, Options } from 'split.js'"},{"note":"When included via a script tag, Split.js makes the `Split` function available globally on the `window` object.","symbol":"UMD Global","correct":""}],"quickstart":{"code":"\n\n\n\n \n \n Split.js Quickstart\n \n\n\n

\n

Panel A

\n

Panel B

\n

Panel C

\n

\n\n \n\n","lang":"typescript","description":"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."},"warnings":[{"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`.","message":"In 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.","severity":"breaking","affected_versions":">=1.5.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<1.5.7"},{"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.","message":"Versions 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.","severity":"gotcha","affected_versions":"<1.5.9"},{"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).","message":"As 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.","severity":"gotcha","affected_versions":">=1.5.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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'])`).","cause":"The selector(s) passed to the Split.js constructor do not match any elements currently in the DOM.","error":"Split.js: Element with selector '#non-existent-id' not found."},{"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.","cause":"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.","error":"Split gutter jumps or behaves erratically during dragging."},{"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`.","cause":"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.","error":"Layout breaks or panels disappear when initial `sizes` are very small, or when `minSize` is greater than the calculated percentage size."}],"ecosystem":"npm"}