SplitMe - Universal Splitter

SplitMe is a universal splitter built with Stencil. It can be embedded in projects using any framework or even plain HTML.

See a Live Demo.

Installing

Option 1 (HTML)

Add the SplitMe script tag to your index.html:

<script src="https://unpkg.com/@resize/split-me/dist/split-me.js"></script>

Option 2 (React / Angular / Vue)

Add SplitMe to your project:

npm install --save @resize/split-me

Import SplitMe in your index.js:

import { defineCustomElements as defineSplitMe } from '@resize/split-me/dist/loader';

defineSplitMe(window);

Basic Usage

Use the split-me tag anywhere you like. Set the number of slots in the splitter through the n attribute. Set the order the inner elements through the slot attribute:

<split-me n="2">
  <div slot="0" class="fill red"></div>
  <div slot="1" class="fill green"></div>
</split-me>

<style>
  .fill {
    height: 100%;
    width: 100%;
  }
</style>

Splitters can be arbitrarily nested into each other to achieve any layout.

<split-me n="3" sizes="0.3, 0.3, 0.4" min-sizes="0.2, 0.0, 0.0">
  <div slot="0" class="fill red"></div>
  <div slot="1" class="fill green"></div>
  <split-me slot="2" n="2" d="vertical" fixed>
      <div slot="0" class="fill blue"></div>
      <div slot="1" class="fill magenta"></div>
  </split-me>
</split-me>

Advanced Usage

Attributes:

• n : number Set the number of slots in the splitter
• d : "horizontal" | "vertical" Set the direction of the splitter
• fixed : boolean Prevent slots from being resized.
• sizes : string Set the initial size of the slots by passing a comma separated array with percentages or fractions. For example: sizes="0.33, 0.67" or sizes="50%, 25%, 25%"
• minSizes : string Set the minimum size of the slots by passing a comma separated array with percentages or fractions.
• maxSizes : string Set the maximum size of the slots by passing a comma separated array with percentages or fractions.
• throttle : number Set the minimum time (in ms) that has to pass between resize events while dragging. Defaults to 0

Events:

• slotResized Fired every time a slot has been resized.

interface IResizeEvent {
  sizes: number[]; // [0.25, 0.75]
  divider: number; // internal divider index
  originalEvent: MouseEvent | TouchEvent; // event of triggered drag
}

Saving State

function handle(event) {
  // extrapolate details
  const { sizes, divider, originalEvent } = event.detail;
  const sourceElement = event.target;

  console.log(sourceElement, originalEvent);
  console.dir({ divider, sizes });

  // store state
  localStorage.setItem('split-sizes', sizes);
}

const el = document.querySelector('split-me');

// loads sizes, but only if they have not been set yet.
el.sizes = el.sizes || localStorage.getItem('split-sizes');

// listen on changes
el.addEventListener('slotResized', handle);

Styling

SplitMe exposes a few CSS variables that can be overridden in order to adjust the styling of the dividers (gutters) to your liking.

This is the list of variables and their default values:

:host {
  --divider-length: 100%; /* Length of the divider along the principal axis */
  --divider-thickness: 0.15rem; /* Thickness of the divider */
  --divider-color: #eeeeee; /* Background color of the divider */
  --divider-shadow: 0 0 0.3rem black; /* Shadow of the divider */
  --divider-image-h: none; /* Background image of the divider when d="horizontal" */
  --divider-image-v: none; /* Background image of the divider when d="vertical" */
  --divider-background-repeat: no-repeat; /* Repeat rule of the background image */
  --divider-background-position: center; /* Position of the background image */
}

Any of these variables can be overridden when using SplitMe in your app. For example, to make the dividers thicker and change their color to yellow:

<split-me n="2">
  <div slot="0" class="fill red"></div>
  <div slot="1" class="fill green"></div>
</split-me>

<style>
  :root split-me {
    --divider-thickness: 0.75rem;
    --divider-color: yellow;
  }
</style>

TODO

• ~~Prevent resizing~~
• ~~Specify initial sizes~~
• ~~Specify minimum and maximum sizes~~
• ~~Customizable splitter style~~