Update v4.2 - New components, 10+ framework guides, and quality improvements. Visit Changelog

........ Github
Figma X (Twitter)

Tailwind CSS Layout Splitter Plugin API

Headless, unstyled layout splitter plugin built with JavaScript and TypeScript, including installation, usage, options, methods, events, and selectors.

JavaScript Typescript

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.

  1. Install the plugin

    Install @preline/layout-splitter via npm

    Terminal 
                              
                            npm i @preline/layout-splitter

  2. Add the plugin 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.

    main.css 
                              
                            @import "tailwindcss";
                            
                            /* @preline/layout-splitter */
                            /* [!code highlight:3] */
                            @source "../node_modules/@preline/layout-splitter/*.js";
                            @import "./node_modules/@preline/layout-splitter/variants.css";
                            @import "./node_modules/@preline/layout-splitter/theme.css";

  3. Add the plugin JavaScript

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

    HTML

    Additional Initialization Options

    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.

    HTML (non-auto)

    Via bundler

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

    JavaScript (auto) 
                              
                            import "@preline/layout-splitter";
    JavaScript (non-auto) 
                              
                            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);

Example

Basic demo with horizontal blocks.

Basic usage

Prefer to create your own style? Here is a completely unstylized example.

HTML 
                      
                        <div data-hs-layout-splitter='{
                          "horizontalSplitterTemplate": "<div><span class=\"absolute top-1/2 inset-s-1/2 -translate-x-2/4 -translate-y-2/4 block w-[11px] h-5 bg-stone-400\"></span></div>",
                          "horizontalSplitterClasses": "relative flex border-s border-stone-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>

JavaScript behavior

Data Options

Name Description Options Default value
data-hs-layout-splitter Activate a Layout Splitter by specifying on an element. Should be added to the container. — —
:horizontalSplitterTemplate Defines the horizontal splitter template. string —
:horizontalSplitterClasses Defines the horizontal splitter CSS classes. string —
:verticalSplitterTemplate Defines the vertical splitter template. string —
:verticalSplitterClasses Defines the vertical splitter CSS classes. string —
data-hs-layout-splitter-horizontal-group Defines a group of elements with horizontal resizable blocks. — —
data-hs-layout-splitter-vertical-group Defines a group of elements with vertical resizable blocks. — —
data-hs-layout-splitter-item 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. float | object —
:dynamicSize Defines the initialized block size.. float —
:minSize Defines the size at which further narrowing of the block will be prevented. float —
:preLimitSize 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. float —

Methods

The HSLayoutSplitter object is contained within the global window object

Method Description
Public methods
getSplitterItemSingleParam(item, name) 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.
  • item the splitter item element.
  • name the name of the parameter to retrieve (e.g. dynamicSize, minSize, preLimitSize).
getData(el) Retrieves detailed information about a splitter item, including its current size, minimum size, and pre-limit size, both in pixels and flex values. The method returns a structured object containing the extracted data.
  • el the splitter item element for which data is retrieved.
setSplitterItemSize(el, size) 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).
  • el the splitter item element to resize.
  • size the desired size of the splitter item as a percentage of the total container size.
updateFlexValues(data) 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.
  • data an array of configuration objects, each containing:
    • id the ID of the splitter item element.
    • breakpoints an object mapping screen widths (breakpoints) to flex values.
destroy() 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
HSLayoutSplitter.getInstance(target, isInstance) Returns the element associated to the target.
  • target should be a Node or string (valid selector)
  • isInstance boolean. Returns the instance instead of Node if true
HSLayoutSplitter.autoInit() Reinitializes all Layout Splitter on the page.

Set different size on window resize.

JavaScript 
                      
                        let layoutSplitter = HSLayoutSplitter.getInstance('#layout-splitter', true);
                        const updateLayoutSplitter = (splitter) => {
                          splitter.updateFlexValues([
                            {
                              id: "section-01",
                              breakpoints: {
                                "0": 0,
                                "1280": 15.0
                              }
                            },
                            {
                              id: "section-02",
                              breakpoints: {
                                "0": 0,
                                "1024": 25.4,
                                "1280": 21.0
                              }
                            },
                            {
                              id: "section-03",
                              breakpoints: {
                                "0": 100,
                                "1024": 74.6,
                                "1280": 64.0
                              }
                            }
                          ]);
                        };

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

Get instance by ID.

JavaScript 
                      
                        const layoutSplitter = new HSLayoutSplitter(document.querySelector('#layout-splitter'));

                        console.log("Instance:", layoutSplitter);

Events

Method Description Returned value
on:drag Called when the splitter is dragged. 
{
  prev: HTMLElement,
  next: HTMLElement,
  previousSize: number,
  previousFlexSize: number,
  nextSize: number,
  nextFlexSize: number
}
on:onPrevLimit Called when the previous section size limit is reached. Previous element
on:onPrevPreLimit Called when the size of the previous section is less than the value of the preLimitSize parameter. Previous element
on:onNextLimit Called when the next section size limit is reached. Next element
on:onNextPreLimit Called when the size of the next section is less than the value of the preLimitSize parameter. Next element

Adds classes that can be useful when you need to minimize the sidebar.

JavaScript 
                      
                        const { element } = HSLayoutSplitter.getInstance('#layout-splitter', true);

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

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

                        element.on('drag', ({ prev, previousFlexSize }) => {
                          if (previousFlexSize > 10) {
                            prev.classList.remove('prev-limit-reached');
                          }
              
                          if (previousFlexSize > 20) {
                            prev.classList.remove('prev-pre-limit-reached');
                          }
                        });

Ready to use Components

Looking for prebuilt UI components based on the Tailwind CSS? Preline UI packs hundreds of component examples for all your website needs.

Layout Splitter

Explore ready-to-use Tailwind CSS examples built with Preline UI.

View Layout Splitter examples

Layout Splitter

© 2026 Preline Labs.