@preline/layout-splitter

Layout Splitter

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

Contents

• Overview
• Installation
• Basic usage
• Configuration Options
• JavaScript API
• Events
• Common Patterns
• License

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.

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.

Static Methods

These methods are called directly on the HSLayoutSplitter class.

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

Copyright (c) 2024 Htmlstream.

Licensed under the MIT License.