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

<script setup>
import { bounds, BoundsFrom, vDraggable } from '@neodrag/vue';
</script>

<template>
  <div>
    <div v-draggable="[bounds(BoundsFrom.viewport())]">
      Can't leave the screen
    </div>
    <div class="container">
      <div v-draggable="[bounds(BoundsFrom.parent())]">
        Contained child
      </div>
    </div>
  </div>
</template>

BoundsFrom Utilities

Viewport Boundaries

<script setup>
import { bounds, BoundsFrom, vDraggable } from '@neodrag/vue';

const basicBounds = [bounds(BoundsFrom.viewport())];
const paddedBounds = [
  bounds(
    BoundsFrom.viewport({
      top: 20,
      left: 20,
      right: 20,
      bottom: 20,
    }),
  ),
];
</script>

<template>
  <div>
    <div v-draggable="basicBounds">Stay in window</div>
    <div v-draggable="paddedBounds">20px padding from edges</div>
  </div>
</template>

Element-Specific Boundaries

<script setup>
import { ref } from 'vue';
import { bounds, BoundsFrom, vDraggable } from '@neodrag/vue';

const container = ref();
const elementBounds = () => [
  bounds(() => BoundsFrom.element(container.value)),
];
const selectorBounds = [bounds(BoundsFrom.selector('#drop-zone'))];
</script>

<template>
  <div>
    <div ref="container" class="boundary-container">
      <div v-draggable="elementBounds">Bound to container</div>
    </div>

    <div class="zone" id="drop-zone">
      <div v-draggable="selectorBounds">Bound by selector</div>
    </div>
  </div>
</template>

Custom Boundary Functions

<script setup>
import { bounds, vDraggable } from '@neodrag/vue';

// 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],
  ];
}

const circularPlugins = [bounds(circularBounds)];
const timePlugins = [bounds(timeBounds)];
</script>

<template>
  <div>
    <div v-draggable="circularPlugins">Circular boundary</div>
    <div v-draggable="timePlugins">Animated boundary</div>
  </div>
</template>

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:

Boundary calculation - Runs the boundary function to get [[x1, y1], [x2, y2]]
Element positioning - Considers the element’s size and current position
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.