README.md

@geoffcox/svelte-splitter

A resizable splitter for Svelte that leverages CSS display:grid

Live Demo

Features

• Vertical (left|right) and Horizontal (top/bottom) splitting
• Provides slots for panes and splitter
• Set initial split size
• Minimum pane sizes
• Sizes can be any CSS unit (e.g. px, %, fr, em, pt, cm, mm)
• Reset to initial split with double-click
• Resize with keyboard arrow keys
• Nested splits with correct resizing
• Customize the DefaultSplitter size & colors, or render your own splitter.

Technology

• Built with Svelte and Typescript
• Package has no dependencies
• CSS grid combined with a simple percentage split system provides accurate and responsive resizing.

Installation

npm install --save @geoffcox/svelte-splitter

Usage

To create vertical or horizontal splits you only need the Split component.

Vertical Split

The default creates a left(50%) | right(50%) split, no minimum pane sizes, and renders the default splitter.

<script>
	import { Split } from '@geoffcox/svelte-splitter';
</script>

<Split>
	<div slot="primary">This is the left pane.</div>
	<div slot="secondary">
		This is the right pane.
		<div></div>
	</div></Split
>

Horizontal Split

Add the horizontal attribute to split top/bottom.

<Split horizontal>
	<div slot="primary">This is the top pane.</div>
	<div slot="secondary">
		This is the bottom pane.
		<div></div>
	</div></Split
>

Set the initial split size

Add the initialPrimarySize property to control where the initial split occurs.

<Split initialPrimarySize="30%">
	<div slot="primary">Primary pane</div>
	<div slot="secondary">
		Secondary pane
		<div></div>
	</div></Split
>

To support double-clicking to reset back to the initial size, add the resetOnDoubleClick property.

<Split initialPrimarySize="30%" resetOnDoubleClick>
	<div slot="primary">Primary pane</div>
	<div slot="secondary">
		Secondary pane
		<div></div>
	</div></Split
>

Nest Splits

Just nest Split componets to create whatever layout you like. Here is an example of a common layout for a main, detail, and output view.

<Split initialPrimarySize="30%">
	<div slot="primary">This is the left pane.</div>
	<svelte:fragment slot="secondary">
		<Split horizontal initialPrimarySize="60%">
			<div slot="primary">This is the right-top pane.</div>
			<div slot="secondary">This is the right-bottom pane.</div>
		</Split>
	</svelte:fragment>
</Split>

Constrain minimum pane sizes

Prevent either pane from becoming too small using the minPrimarySize and minSecondarySize properties.

<Split minPrimarySize="250px" minSecondarySize="15%">
	<div slot="primary">This pane won't get smaller than 250 pixels.</div>
	<div slot="secondary">
		This pane won't get any smaller than 15% of the overall size of the split control./
		<div></div>
	</div></Split
>

Customize the splitter size

Set the size of the default splitter's hit area with the splitterSize property. The hit area is where the user can click to start dragging the splitter.

<Split splitterSize="10px">
	<div slot="primary">Primary pane</div>
	<div slot="secondary">
		Secondary pane
		<div></div>
	</div></Split
>

Customize the splitter colors

Change the colors of the default splitter by adding the DefaultSplitter to the splitter slot. Pass color properties to the default splitter.

<Split defaultSplitterColors={colors}>
  <div slot="primary">Primary pane</div>
  <svelte:fragment slot="splitter">
    <DefaultSplitter color="red" hoverColor="#00FF00" dragColor="blue">
  </svelte:fragment>
  <div slot="secondary">Secondary pane<div>
</Split>

Custom render the splitter

Substitute a custom splitter by replacing the default splitter.

<Split defaultSplitterColors={colors}>
	<div slot="primary">Primary pane</div>
	<svelte:fragment slot="splitter">
		<MyAwesomeSplitter />
	</svelte:fragment>
	<div slot="secondary">
		Secondary pane
		<div></div>
	</div></Split
>

When building a customer splitter, leverage the context information from the parent Split component.

let splitterContext = getContext<SplitterContextStore>(splitterContextKey);

$: dragging = $splitterContext.dragging;
$: horizontal = $splitterContext.horizontal;
};

Events

Subscribe to the changed event to get updates.

const onChanged = (event) => {
    const {details: {percent, primarySize, splitterSize, secondarySize, dragging}} = event;
    console.log(`percent: ${percent}`);
    console.log(`primarySize: ${primarySize}`);
    console.log(`splitterSize: ${splitterSize}`);
    console.log(`secondarySize: ${secondarySize}`);
    console.log(`dragging: ${dragging}`);
};
```ts

```svelte
<Split on:changed={onChanged}>
    ...
</Split>

Imperative Methods

Get or set the percentage by calling getPercent and setPercent on the Split handle.

let splitControl;

const flipSplitPercent = () => {
	const percent = splitControl.getPercent();
	splitControl.setPercent(100 - percent);
};

<Split bind:this={splitControl}>...</Split>

Known limitations

• No typescript definitions for Split or DefaultSplitter

Change History

1.0.0 - First project publication

• Based on the 2.1.0 version of @geoffcox/react-splitter
• Updated to idomatic Svelte

1.0.1 - Updated live demo link