<lit-movable>
Movable element - simple and robust. A wrapper web component that can enable customizable element move operations and expose pointer state data.
Since this is a Lit 3 web component, this will work inside any SPA framework. React integration docs. Framework-agnostic web components are the future!
Installation
npm i lit-movable
Basic Usage
<script type="module">
import {LitMovable} from 'lit-movable';
</script>
<lit-movable>
<div style="background:lightsteelblue">I am movable</div>
</lit-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
<lit-movable id="myMovable"></lit-movable>
<script>
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
});
</script>
More usage examples
Modal behavior
Parent moves when title is dragged. Used targetSelector attribute.
<div style="height:200px;width:200px;border:solid 1px blue;" id="dialog">
<lit-movable targetSelector="#dialog">
<div style="background:lightsteelblue;width:100%">I am a draggable title</div>
</lit-movable>
I am not directly grabbable, but I will move if you grab my title.
</div>
Horizontal only
Constrain vertical movement. Allow -50 -> 250 horizontal movement. Here are two ways to accomplish the identical behavior.
<!-- Set horizontal movement only -->
<lit-movable horizontal="-50,250">
<div style="background:lightsteelblue">Move me horizontally</div>
</lit-movable>
<!-- OR -->
<!-- Explicit x/y boundaries. Null string constrains an axis -->
<lit-movable boundsX="-50,250" boundsY="null">
<div style="background:lightsteelblue">Move me horizontally</div>
</lit-movable>
Vertical only
Two identical ways to constrain horizontal movement, but enable broad vertical motion.
<!-- Set vertical movement only -->
<lit-movable vertical="-999,9999">
<div style="background:lightsteelblue">Move me vertically</div>
</lit-movable>
<!-- Alternate explicit bounds (x,y) equivalent. Null = no movement enabled -->
<lit-movable boundsY="-999,9999" boundsX="null">
<div style="background:lightsteelblue">Move me horizontally</div>
</lit-movable>
Snapping / shift key option enabled
Snaps to a 50px grid with shift key behavior.
<lit-movable grid="50" shiftBehavior="true">
<div style="background:lightsteelblue">my grid is 50 <br>(try holding shift while dragging)</div>
</lit-movable>
Constrain both directions
Start in middle of a constrained box.
<div style="height:200px;width:200px;border:solid 1px green;position:relative">
<lit-movable posTop="100" posLeft="100" boundsX="-100,100" boundsY="-100,100">
<div style="background:lightsteelblue;width:30px;margin-left:-15px;height:18px;margin-top:-9px">
box
</div>
</lit-movable>
</div>
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.
git clone https://github.com/thewebkid/lit-movable.git
cd ./lit-movable
npm i
npm dev