a-multilayout-splitter

a-multilayout-splitter is a versatile React component designed for creating dynamic, resizable layouts with collapsible panes. It supports both horizontal and vertical orientations, allowing for a flexible arrangement of UI components. With features like minimum and maximum size validation, custom handlebars, and programmable collapse and expand functionalities, it's the perfect tool for developing responsive and interactive layouts.

Table of Contents

• Installation
• Usage
  • Basic Example
  • Orientation
  • Collapsible Panes
  • Initial State and Sizes
  • Pixel and Percentage Support
    • Sizes in Pixel
    • Sizes in Percentage
    • Sizes in Pixel and Percentage both
  • Programmatic Collapse and Expand
  • Min and Max Sizes
  • Disabling Resize
  • Custom Handlebar
  • Nested Layout
• Features
• License
• Limitations

Installation

To install the package, run the following command in your project directory:

npm install a-multilayout-splitter

or if you use yarn:

yarn add a-multilayout-splitter

Usage

Note:

This project is actively maintained, and the documentation is regularly updated. For now, the examples and guidance provided here should help you get started.

Basic Example

To add a splitter to your application, use the <Split> component with child elements representing the components you want to split. By default, the splitter will occupy 100% of the height and width of its parent container.

CodeSanbox Example

Note:

The id prop is crucial as it helps you easily identify the instance of each split. You can refer to the Programmatic Collapse and Expand section for more information.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split mode="horizontal" id="split1">
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>;

Orientation

Control the orientation of the panes by setting the mode property to either 'horizontal' or 'vertical'.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split mode="vertical" id="split1">
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>;

Collapsible Panes

Enable or disable the collapsible functionality using the lineBar property.

• By default, collapsible behavior is enabled.
• To disable, set lineBar without any value or with specific handlebar positions.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split id="split1" mode="horizontal" lineBar>
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>;

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split id="split1" mode="horizontal" lineBar={[1, 3]}>
    <div>Pane 1</div>
    <div>Pane 2</div>
    <div>Pane 3</div>
    <div>Pane 4</div>
  </Split>
</SplitStateProvider>;

Initial State and Sizes

Define initial sizes and collapsed state for panes to enhance user experience.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split id="split1" mode="horizontal" initialSizes={["200px", "200px", "200px"]} collapsed={[true, false, true]} width="600px" height="100px">
    <div>Pane 1</div>
    <div>Pane 2</div>
    <div>Pane 3</div>
  </Split>
</SplitStateProvider>;

Pixel and percentage support

You can also define the sizes for splitter pane using initialSizes property. It accepts an array of string. Splitter pane sizes supports pixel and percentage. You can provide combination of pixel and percentage also.

Sizes in pixel

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split mode="horizontal" width="200px" height="100px" initialSizes={["100px", "100px"]}>
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>;

Sizes in percentage

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split mode="horizontal" width="200px" height="100px" initialSizes={["50%", "50%"]}>
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>;

Sizes in pixel and percentage both

<SplitStateProvider>
  <Split mode="horizontal" width="200px" height="100px" initialSizes={["100%", "50%"]}>
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>

Programmatic Collapse and Expand

Use SplitUtils to programmatically control the panes.

Note:

For collapsing and expanding split panes, it's necessary to provide the instance. Each split instance is stored under the given split ID, allowing you to easily use that ID and pass the instance when needed. To retrieve all splitter instances, you can utilize SplitUtils.getSplitInstance() by providing the key (i.e., the ID) of the specific splitter on which you want to expand or collapse. This approach ensures precise control over the behavior of split panes.

import { Split, closeSplitter, openSplitter, getSplitInstance, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split mode='horizontal' id='split1'>
    <div>Pane 1</div>
    <div>Pane 2</div>
    <div>Pane 3</div>
    <div>Pane 4</div>
  </Split>
</SplitStateProvider>
<button onClick={() => closeSplitter(getSplitInstance()['split1'], 2,"horizontal")}>Collapse</button>
<button onClick={() => openSplitter(getSplitInstance()['split1'], 2, "horizontal")}>Expand</button>

Min and Max Sizes

Restrict pane sizes with minimum and maximum values.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split id="split1" mode="horizontal" minSizes={[20, 20]} maxSizes={[80, 80]}>
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>;

Disabling Resize

Disable resizing entirely or for specific handlebars.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split id="split1" mode="horizontal" disable>
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>;

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split id="split1" mode="horizontal" disable={[1, 2]}>
    <div>Pane 1</div>
    <div>Pane 2</div>
    <div>Pane 3</div>
    <div>Pane 4</div>
  </Split>
</SplitStateProvider>;

Custom Handlebar

Implement custom handlebars with the renderBar property. Currently, custom handlebars do not support the 'disable' and 'lineBar' properties.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<SplitStateProvider>
  <Split id='split1' mode="horizontal" renderBar={() => /* Custom render function */}>
    <div>Pane 1</div>
    <div>Pane 2</div>
  </Split>
</SplitStateProvider>

Nested Layout

When dealing with deeply nested layouts, you may encounter resizing issues where the layout does not expand or grow as expected. To address this issue, the fixClass property and SplitUtils.fixClass() method are provided as solutions. By applying the fixClass property to the appropriate splitter, you can dynamically adjust the layout to ensure proper resizing behavior.

import { Split, SplitStateProvider } from "a-multilayout-splitter";

<div className="App" style={{ width: "100%", height: "500px" }}>
  <SplitStateProvider>
    <Split mode="vertical" id="splitter1">
      <Split mode="horizontal" id="splitter2" collapsed={[false, false]}>
        <div>Pane 1</div>
        <Split mode="vertical" id="splitter3" collapsed={[false, false]}>
          <div>Pane 2</div>
          <Split mode="horizontal" id="splitter4" collapsed={[false, false, false]} fixClass>
            <div className={SplitUtils.fixClass()}>Pane 3</div>
            <div>Pane 4</div>
            <div>Pane 5</div>
          </Split>
        </Split>
      </Split>
      <Split mode="horizontal" id="splitter5" collapsed={[false, false]}>
        <div>Pane 6</div>
        <div>Pane 7</div>
      </Split>
    </Split>
  </SplitStateProvider>
</div>;

Local Storage

To resume your layout from where you left off before closing the tab or browser, you can enable the enableSessionStorage option. By default, this option is set to false. Once enabled, your layout will be saved, allowing you to seamlessly continue your work from the last saved state.

Features

• Lightweight and Fast: Designed to be lightweight and deliver optimal performance.
• Flexible Orientation: Supports horizontal and vertical layouts.
• Collapsible Panes: Built-in expand and collapse functionality.
• Customizable Sizes: Set initial, minimum, and maximum sizes.
• Programmatic Control: Dynamically collapse or expand panes.
• Custom Handlebars: Extend with custom handlebar designs.
• Responsive Design: Adapts to various screen sizes and layouts.

Limitations

• Nested Layout Issues: Local Storage does not support nested layouts, resulting in unexpected behavior when nested layouts have more than two levels.
• Difficulty in Managing Nested Layouts: There is currently no built-in provision to address nested layout issues caused by internal methods. Users may need to utilize the fixClass prop or the fixClass method provided by SplitUtils to mitigate these issues.
• Limitations of Custom Handlebars: The custom handleBar feature does not support the disable and lineBar functionalities, which may restrict its usability in certain scenarios.

For more information and advanced usage, please refer to the documentation.

Contributions, issues, and feature requests are welcome!

License

This project is licensed under the MIT License - see the LICENSE file for details.