@preline/layout-splitter

v4.2.0

Published

9 days ago

Preline UI is an open-source set of prebuilt UI components based on the utility-first Tailwind CSS framework.

Layout Splitter

Customize your layout effortlessly by adjusting block sizes to your preference with Tailwind CSS Layout Splitters.

Overview

The Layout Splitter component provides resizable layout panels with drag handles. It allows users to adjust the size of layout sections horizontally or vertically, creating flexible and customizable interfaces.

Key Features:

Horizontal and vertical resizing
Drag handles for intuitive resizing
Minimum size constraints
Pre-limit size detection
Responsive breakpoint support
Programmatic control via JavaScript API
Event system for drag tracking

Installation

To get started, install Layout Splitter plugin via npm, else you can skip this step if you are already using Preline UI as a package.

npm i @preline/layout-splitter

CSS

Use @source to register the plugin's JavaScript path for Tailwind CSS scanning, then @import the plugin's CSS files into your Tailwind CSS file.

@import "tailwindcss";

/* @preline/layout-splitter */
@source "../node_modules/@preline/layout-splitter/*.js";
@import "./node_modules/@preline/layout-splitter/variants.css";
@import "./node_modules/@preline/layout-splitter/theme.css";

JavaScript

Include the JavaScript that powers the interactive elements near the end of your </body> tag:

<script src="./node_modules/@preline/layout-splitter/index.js"></script>

Manual Initialization

Use the non-auto entry if you need manual initialization. In this mode, automatic initialization on page load is not included, so the component should be initialized explicitly.

<script type="module">
  import HSLayoutSplitter from "@preline/layout-splitter/non-auto.mjs";

  new HSLayoutSplitter(document.querySelector("#layout-splitter"));
</script>

Via Bundler

When using a bundler (Vite, webpack, etc.), import the plugin directly as an ES module.

@preline/layout-splitter is the auto-init entry: it scans the DOM and initializes matching elements automatically.

import "@preline/layout-splitter";

@preline/layout-splitter/non-auto is the manual entry: use it when you want explicit control over when initialization happens, either via autoInit() or by creating a specific instance yourself.

import HSLayoutSplitter from "@preline/layout-splitter/non-auto";

HSLayoutSplitter.autoInit();

// Or initialize a specific element manually
const el = document.querySelector("#layout-splitter");
if (el) new HSLayoutSplitter(el);

TypeScript

This package ships with TypeScript type definitions. No additional @types/ package is needed.

Basic usage

The following example demonstrates the minimal HTML structure required for a layout splitter component. This is a base template without custom styling - you can apply your own CSS classes and styles as needed. The layout allows resizing blocks by dragging the splitter handle.

<div data-hs-layout-splitter='{
  "horizontalSplitterTemplate": "<div><span class=\"absolute top-1/2 start-1/2 -translate-x-2/4 -translate-y-2/4 block w-[11px] h-5 bg-gray-400\"></span></div>",
  "horizontalSplitterClasses": "relative flex border-s border-gray-200"
}'>
  <div class="flex h-50" data-hs-layout-splitter-horizontal-group>
    <div class="h-full" data-hs-layout-splitter-item="48.2">Horizontal Block 1</div>
    <div class="h-full" data-hs-layout-splitter-item="30.0">Horizontal Block 2</div>
  </div>
</div>

Structure Requirements:

data-hs-layout-splitter: Required on the container element, contains configuration options as JSON
data-hs-layout-splitter-horizontal-group: Required for horizontal splitting
data-hs-layout-splitter-vertical-group: Required for vertical splitting
data-hs-layout-splitter-item: Required on resizable blocks, accepts float number or object for initial size

Initial State:

Blocks are sized according to data-hs-layout-splitter-item values
Splitter handles are visible and draggable

Configuration Options

Data Options

Data options are specified in the data-hs-layout-splitter attribute and on splitter items.

| Option | Target Element | Type | Default | Description | | --- | --- | --- | --- | --- | | data-hs-layout-splitter | Container | - | - | Activate a Layout Splitter by specifying on an element. Should be added to the container. | | :horizontalSplitterTemplate | Inside data-hs-layout-splitter | string (HTML markup) | - | Defines the horizontal splitter template. HTML markup for the drag handle. | | :horizontalSplitterClasses | Inside data-hs-layout-splitter | string | - | Defines the horizontal splitter CSS classes. CSS classes must be separated by a space. | | :verticalSplitterTemplate | Inside data-hs-layout-splitter | string (HTML markup) | - | Defines the vertical splitter template. HTML markup for the drag handle. | | :verticalSplitterClasses | Inside data-hs-layout-splitter | string | - | Defines the vertical splitter CSS classes. CSS classes must be separated by a space. | | data-hs-layout-splitter-horizontal-group | Container element | - | - | Defines a group of elements with horizontal resizable blocks. | | data-hs-layout-splitter-vertical-group | Container element | - | - | Defines a group of elements with vertical resizable blocks. | | data-hs-layout-splitter-item | Resizable block | float | object | - | Defines a block that can be resized depending on what group it is in. Also accepts a float number as a value to specify the initial width or height of the element. Can be an object with dynamicSize, minSize, preLimitSize properties. | | :dynamicSize | Inside data-hs-layout-splitter-item | float | - | Defines the initialized block size. | | :minSize | Inside data-hs-layout-splitter-item | float | - | Defines the size at which further narrowing of the block will be prevented. | | :preLimitSize | Inside data-hs-layout-splitter-item | float | - | Determines the size at which the onPrevPreLimit event will be called. For example, on this event you can add specific classes to the block to the right or left of the divider. |

Example:

<div data-hs-layout-splitter-item='{
  "dynamicSize": 30.0,
  "minSize": 10.0,
  "preLimitSize": 20.0
}'>
  Resizable Block
</div>

JavaScript API

The HSLayoutSplitter object is available in the global window object after the plugin is loaded.

Instance Methods

These methods are called on a layout splitter instance.

| Method | Parameters | Return Type | Description | | --- | --- | --- | --- | | getSplitterItemSingleParam(item, name) | item: HTMLElement (splitter item element)name: string (parameter name) | any | Retrieves the value of a specific parameter (name) from the data attribute of a splitter item (item). The parameter is extracted from the parsed JSON object stored in the data-hs-layout-splitter-item attribute. | | getData(el) | el: HTMLElement (splitter item element) | object | Retrieves detailed information about a splitter item, including its current size, minimum size, and pre-limit size, both in pixels and flex values. Returns a structured object. | | setSplitterItemSize(el, size) | el: HTMLElement (splitter item element)size: number (percentage) | void | Updates the size of a specified splitter item (el) to the given value (size). The new size is converted into a flex value and applied to the element. The method also updates the corresponding data attribute (data-hs-layout-splitter-item). | | updateFlexValues(data) | data: Array<{ id: string, breakpoints: Record<number, number> }> | void | Updates the flex values of splitter items based on the provided configuration. Each configuration object specifies an element's ID and its size values for different screen widths (breakpoints). The method dynamically adjusts the flex values of the specified elements to match the current screen width. | | destroy() | None | void | Cleans up and removes all event listeners, styles, and data attributes associated with the layout splitter. This method restores the affected elements to their original state and releases resources. |

Static Methods

These methods are called directly on the HSLayoutSplitter class.

| Method | Parameters | Return Type | Description | | --- | --- | --- | --- | | HSLayoutSplitter.getInstance(target, isInstance) | target: HTMLElement \| string (CSS selector)isInstance: boolean (optional) | HTMLElement \| { id: string \| number, element: HSLayoutSplitter } \| null | Returns the layout splitter instance or element associated with the target. If isInstance is true, returns collection item object { id, element } where element is the HSLayoutSplitter instance. If isInstance is false or omitted, returns the DOM element (HTMLElement). Returns null if layout splitter instance is not found. | | HSLayoutSplitter.autoInit() | None | void | Reinitializes all Layout Splitters on the page. Useful after dynamically adding layout splitters to DOM. |

Usage Examples

Example 1: Getting splitter item data

// Get the layout splitter instance
const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  const item = document.querySelector('#hs-splitter-item');
  // Get item data
  const data = element.getData(item);

  console.log('Item data:', data);
}

Example 2: Setting splitter item size

const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  const item = document.querySelector('#hs-splitter-item');

  // Set item size to 50%
  element.setSplitterItemSize(item, 50);
}

Example 3: Responsive breakpoints

const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  // Update flex values based on window size
  const updateLayoutSplitter = (splitter) => {
    splitter.updateFlexValues([
      {
        id: "hs-section-first",
        breakpoints: {
          "0": 0,
          "1280": 15.0
        }
      },
      {
        id: "hs-section-second",
        breakpoints: {
          "0": 0,
          "1024": 25.4,
          "1280": 21.0
        }
      },
      {
        id: "hs-section-third",
        breakpoints: {
          "0": 100,
          "1024": 74.6,
          "1280": 64.0
        }
      }
    ]);
  };

  window.addEventListener('resize', () => {
    if (instance) updateLayoutSplitter(instance.element);
  });
}

Example 4: Destroying layout splitter instance

const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;
  const removeBtn = document.querySelector('#hs-remove-btn');

  removeBtn.addEventListener('click', () => {
    // Clean up before removing from DOM
    element.destroy();
    // Now safe to remove the element
    document.querySelector('#hs-layout-splitter').remove();
  });
}

Events

Layout splitter instances emit events that can be listened to for drag tracking and custom behavior.

| Event Name | When Fired | Callback Parameter | Description | | --- | --- | --- | --- | | on:drag | When the splitter is dragged | { prev: HTMLElement, next: HTMLElement, previousSize: number, previousFlexSize: number, nextSize: number, nextFlexSize: number } | Fires when the splitter is being dragged. Returns an object with previous and next elements and their sizes. | | on:onPrevLimit | When the previous section size limit is reached | HTMLElement (previous element) | Fires when the previous section reaches its minimum size limit. | | on:onPrevPreLimit | When the previous section size is less than preLimitSize | HTMLElement (previous element) | Fires when the previous section size is less than the preLimitSize parameter value. | | on:onNextLimit | When the next section size limit is reached | HTMLElement (next element) | Fires when the next section reaches its minimum size limit. | | on:onNextPreLimit | When the next section size is less than preLimitSize | HTMLElement (next element) | Fires when the next section size is less than the preLimitSize parameter value. |

Event Usage Example

// Get layout splitter instance
const instance = HSLayoutSplitter.getInstance('#hs-layout-splitter', true);

if (instance) {
  const { element } = instance;

  // Listen to limit events
  element.on('onPrevLimit', (prev) => {
    prev.classList.add('hs-prev-limit-reached');
  });

  element.on('onPrevPreLimit', (prev) => {
    prev.classList.add('hs-prev-pre-limit-reached');
  });

  // Listen to drag event
  element.on('drag', ({ prev, previousFlexSize }) => {
    if (previousFlexSize > 10) {
      prev.classList.remove('hs-prev-limit-reached');
    }

    if (previousFlexSize > 20) {
      prev.classList.remove('hs-prev-pre-limit-reached');
    }
  });
}

Common Patterns

Pattern 1: Horizontal Splitter

Create horizontal resizable panels.

<div data-hs-layout-splitter>
  <div data-hs-layout-splitter-horizontal-group>
    <div data-hs-layout-splitter-item="50">Left Panel</div>
    <div data-hs-layout-splitter-item="50">Right Panel</div>
  </div>
</div>

Pattern 2: With Minimum Size

Set minimum size constraints.

<div data-hs-layout-splitter-item='{
  "dynamicSize": 30.0,
  "minSize": 10.0
}'>
  Resizable Panel
</div>

License

Licensed under the MIT License.