Split.js

Common errors

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

  cause 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.

  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.
  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.

  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.
  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`.

Warnings

• breaking 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.
  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`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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).

Install

• npm install split.js npm
• yarn add split.js yarn
• pnpm add split.js pnpm

Imports

• Split
  wrong:

  const Split = require('split.js')

  correct:

  import Split from '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.

Quickstart

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.

<!-- index.html -->
<!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>