Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alesgenova/split-me
Universal web component to create resizable split layouts
https://github.com/alesgenova/split-me
html javascript split-layout splitter stenciljs typescript webcomponents
Last synced: about 1 month ago
JSON representation
Universal web component to create resizable split layouts
- Host: GitHub
- URL: https://github.com/alesgenova/split-me
- Owner: alesgenova
- License: mit
- Created: 2018-07-07T02:18:55.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T18:03:42.000Z (almost 2 years ago)
- Last Synced: 2024-10-31T10:41:22.413Z (about 1 month ago)
- Topics: html, javascript, split-layout, splitter, stenciljs, typescript, webcomponents
- Language: TypeScript
- Homepage:
- Size: 1.1 MB
- Stars: 75
- Watchers: 5
- Forks: 13
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-stenciljs - SplitMe
README
[](https://www.npmjs.com/package/split-me)
[](https://github.com/alesgenova/split-me/actions?query=workflow%3Amain+branch%3Amaster)
[](https://www.webcomponents.org/element/split-me)
[](https://stenciljs.com)
# SplitMe - Universal Splitter
`SplitMe` is a universal splitter built with [Stencil](http://stenciljs.com). It can be embedded in projects using any framework or even plain HTML.
See a [Live Demo](https://alesgenova.github.io/split-me/).
[](https://alesgenova.github.io/split-me/)
## Table of Contents
- [Setup](#setup)
- [Basic Usage](#basic-usage)
- [Advanced Usage](#advanced-usage)
- [Properties](#properties)
- [Events](#events)
- [Saving State](#saving-state)
- [Styling](#styling)
## Setup
### Option 1 (HTML)
Add the `SplitMe` script tag to your `index.html`:
```
```
### Option 2 (React / Angular / Vue)
Add `SplitMe` to your project:
```
npm install --save split-me
```
Import `SplitMe` in your `index.js`:
```js
import { defineCustomElements as defineSplitMe } from 'split-me/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:
```html
.fill {
height: 100%;
width: 100%;
}
```
Splitters can be arbitrarily nested into each other to achieve any layout.
```html
```
## Advanced Usage
### Properties
| Property | Attribute | Description | Type |
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `d` | `d` | The direction of the splitter. | `"horizontal" \| "vertical"` |
| `fixed` | `fixed` | Prevent the splitter from being resized. | `boolean` |
| `maxSizes` | `max-sizes` | The maximum sizes of the slots. Same format as `sizes` | `number[] \| string` |
| `minSizes` | `min-sizes` | The minimum sizes of the slots. Same format as `sizes` | `number[] \| string` |
| `n` | `n` | The number of slots in the splitter. | `number` |
| `sizes` | `sizes` | The initial sizes of the slots. Acceptable formats are: `sizes="0.33, 0.67"` or `sizes="50%, 25%, 25%"` | `number[] \| string` |
| `throttle` | `throttle` | The minimum time (in ms) between resize events while dragging. | `number` |
### Events
| Event | Detail | Description |
| ------------- | ------------ | ------------------------------------------------------ |
| `slotResized` | IResizeEvent | Emitted every time dragging causes the slots to resize |
```typescript
interface IResizeEvent {
sizes: number[]; // [0.25, 0.75]
divider: number; // internal divider index
originalEvent: MouseEvent | TouchEvent; // event that triggered resize
}
```
#### Saving State
```javascript
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:
```css
: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 */
--phantom-divider-thickness: 2rem; /* Thickness of the phantom divider used to grab mouse events */
}
```
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:
```html
:root split-me {
--divider-thickness: 0.75rem;
--divider-color: yellow;
}
```
## TODO
- ~~Prevent resizing~~
- ~~Specify initial sizes~~
- ~~Specify minimum and maximum sizes~~
- ~~Customizable splitter style~~