Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thewebkid/lit-movable
A Lit 3 wrapper web component that can enable robustly customizable element move operations and expose rich state data.
https://github.com/thewebkid/lit-movable
draggable draggable-elements lit lit-element movable web-component
Last synced: 3 days ago
JSON representation
A Lit 3 wrapper web component that can enable robustly customizable element move operations and expose rich state data.
- Host: GitHub
- URL: https://github.com/thewebkid/lit-movable
- Owner: thewebkid
- License: mit
- Created: 2023-11-13T20:37:05.000Z (11 months ago)
- Default Branch: master
- Last Pushed: 2024-02-04T00:23:25.000Z (8 months ago)
- Last Synced: 2024-09-21T02:32:12.391Z (6 days ago)
- Topics: draggable, draggable-elements, lit, lit-element, movable, web-component
- Language: JavaScript
- Homepage: https://thewebkid.com/modules/lit-movable
- Size: 230 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# \ [](https://badge.fury.io/js/lit-movable) [](https://opensource.org/licenses/MIT)
Movable element - simple and robust. A wrapper web component that can enable customizable element move operations and expose pointer state data.
[Live Demo](http://thewebkid.com/modules/lit-movable)
Since this is a [Lit 3 web component](https://lit.dev/), this will work inside any SPA framework. [React integration docs](https://lit.dev/docs/frameworks/react/). Framework-agnostic web components are the future!
## Installation
```bash
npm i lit-movable
```
## Basic Usage
```html
import {LitMovable} from 'lit-movable';
I am movable
```
### Attributes
- **posTop**: _Number_ - Represents the offsetTop/Left value (reflected). When set, will set the initial _style.top_ value. Updates with move events
- **posTop**: _Number_ - Represents the offsetLeft value (reflected). When set, will set the initial style.top value. Updates with move events
- **targetSelector**: _String_ - A selector to select the element that will move. Defaults to the lit-movable (this) element, but useful when for example you want to allow a modal header to respond to pointer events but you want the entire modal to move.
- **boundsX**: _String: boundsX="min,max"_ Defaults to -Infinity,Infinity. Set to restrict movement along the x axis.
- **boundsY**: _String: boundsY="min,max"_ Defaults to -Infinity,Infinity. Set to restrict movement along the y axis.
- **vertical**: _String: vertical="min,max"_ - Will constrain horizontal (x) movement completely and allow vertical (y) movement between the specified values.
- **horizontal**: _String: horizontal="min,max"_ - Will constrain vertical (y) movement completely and allow horizontal (x) movement between the specified values.
- **grid**: _Number_ - Snaps movement to nearest grid position (defaults to 1). Initial element position represents the 0,0 position. Movement snapped to the provided value increment
- **shiftKey** _Bool_ - When enabled, holding the shift key will coerce movement to perpendicular coordinates only.
- **disabled**: _Bool_ - Disables movement behavior.
- **eventsOnly**: _Bool_ - (advanced) Only fires movement events, but will not move the element.
## Events
Lit-Movable exposes events as either callback properties or the built in custom events.
### Event Properties
- **onmovestart**: called immediately after the pointerdown event on the element
- **onmove**: called continuously while moving
- **onmoveend**: called after the pointerup event on the element
### Custom Events
- **movestart**: fires immediately after the pointerdown event on the element
- **move**: fires continuously while moving
- **moveend**: fires after the pointerup event on the element
### Event binding examples
```html
const movableEl = document.getElementById("myMovable");
/* Bind As property */
movableEl.onmove = (moveState)=>{
const {coords, clickOffset, mouseCoord, moveDist, startCoord, totalDist} = moveState;
//all coordinates expose x,y,top,left
console.log(coords);//Current element pos
console.log(clickOffset);// the position of the pointer relative to the top/left of the element
console.log(mouseCoord); // current mouse pos on page - equivalent of pageX/pageY on a mouse event
console.log(moveDist); //distance moved since previous move operation
console.log(startCoord); //position of element on pointerdown
console.log(totalDist);//distance moved from pointerdown to pointerup
}
/* Custom Event */
movableEl.addEventListener('move', (event) => {
const moveState = event.detail;
console.log({moveState});//same state object as above
});
```
## More usage examples
#### Modal behavior
Parent moves when title is dragged. Used targetSelector attribute.
```html
I am a draggable title
I am not directly grabbable, but I will move if you grab my title.
```
#### Horizontal only
Constrain vertical movement. Allow -50 -> 250 horizontal movement. Here are two ways to accomplish the identical behavior.
```html
Move me horizontally
Move me horizontally
```
#### Vertical only
Two identical ways to constrain horizontal movement, but enable broad vertical motion.
```html
Move me vertically
Move me horizontally
```
#### Snapping / shift key option enabled
Snaps to a 50px grid with shift key behavior.
```html
my grid is 50
(try holding shift while dragging)
```
#### Constrain both directions
Start in middle of a constrained box.
```html
box
```
## Run local
Uses vite. Will run on node 16+ but will complain about compatibility if you are stuck on node 16 like me. Ignore this. It's fine.
```bash
git clone https://github.com/thewebkid/lit-movable.git
cd ./lit-movable
npm i
npm dev
```