bounds

Keep draggable elements within specified boundaries

The bounds plugin keeps draggable elements within specified boundaries. Whether it’s staying inside a parent container, the viewport, or custom regions - bounds ensures your elements can’t escape their designated areas.

bounds(BoundsFrom.viewport()); // Stay in browser window
bounds(BoundsFrom.parent()); // Stay in parent element
bounds(BoundsFrom.element(el)); // Stay in specific element

Basic Usage

import { bounds, BoundsFrom, Draggable } from '@neodrag/vanilla';

const viewportElement = document.getElementById('viewport-bound');
const parentElement = document.getElementById('parent-bound');

new Draggable(viewportElement, [bounds(BoundsFrom.viewport())]);
new Draggable(parentElement, [bounds(BoundsFrom.parent())]);

BoundsFrom Utilities

Viewport Boundaries

import { bounds, BoundsFrom, Draggable } from '@neodrag/vanilla';

const basic = document.getElementById('basic');
const padded = document.getElementById('padded');

new Draggable(basic, [bounds(BoundsFrom.viewport())]);
new Draggable(padded, [
  bounds(
    BoundsFrom.viewport({
      top: 20,
      left: 20,
      right: 20,
      bottom: 20,
    }),
  ),
]);

Element-Specific Boundaries

import { bounds, BoundsFrom, Draggable } from '@neodrag/vanilla';

const container = document.getElementById('container');
const bounded = document.getElementById('bounded');
const selector = document.getElementById('selector');

new Draggable(bounded, [bounds(() => BoundsFrom.element(container))]);
new Draggable(selector, [bounds(BoundsFrom.selector('#drop-zone'))]);

Custom Boundary Functions

import { bounds, Draggable } from '@neodrag/vanilla';

const circular = document.getElementById('circular');
const time = document.getElementById('time');

// Custom circular boundary
function circularBounds() {
  const centerX = window.innerWidth / 2;
  const centerY = window.innerHeight / 2;
  const radius = 200;

  return [
    [centerX - radius, centerY - radius],
    [centerX + radius, centerY + radius],
  ];
}

// Dynamic boundary based on time
function timeBounds() {
  const time = Date.now() / 1000;
  const padding = Math.sin(time) * 50 + 100;

  return [
    [padding, padding],
    [window.innerWidth - padding, window.innerHeight - padding],
  ];
}

new Draggable(circular, [bounds(circularBounds)]);
new Draggable(time, [bounds(timeBounds)]);

Dynamic Boundaries

For boundaries that change during dragging, control when they’re recalculated:

bounds(boundaryFunction, (ctx) => {
  // Recompute on every drag event
  return ctx.hook === 'drag';
});

bounds(boundaryFunction, (ctx) => {
  // Only recompute at start and end
  return ctx.hook === 'dragStart' || ctx.hook === 'dragEnd';
});

How It Works

The bounds plugin calculates the allowed movement area and clamps the proposed position:

1. Boundary calculation - Runs the boundary function to get [[x1, y1], [x2, y2]]
2. Element positioning - Considers the element’s size and current position
3. Movement clamping - Limits proposed.x and proposed.y to stay within bounds

The boundary function is called:

• On drag start (always)
• During drag (if shouldRecompute returns true)
• On drag end (if shouldRecompute returns true)

API Reference

function bounds(
  boundsFn: () => [[number, number], [number, number]],
  shouldRecompute?: (ctx: {
    hook: 'dragStart' | 'drag' | 'dragEnd';
  }) => boolean,
): Plugin;

Parameters:

• boundsFn - Function returning [[x1, y1], [x2, y2]] coordinates
• shouldRecompute - When to recalculate boundaries (default: drag start only)

BoundsFrom utilities:

• BoundsFrom.viewport(padding?) - Browser viewport
• BoundsFrom.parent(padding?) - Parent element
• BoundsFrom.element(el, padding?) - Specific element
• BoundsFrom.selector(selector, padding?, root?) - Element by selector

Returns: A plugin object for use with draggable.