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>
  import { bounds, BoundsFrom } from '@neodrag/svelte';
</script>

<!-- Stay within viewport -->
<div {@attach draggable([bounds(BoundsFrom.viewport())])}>
  Can't leave the screen
</div>

<!-- Stay within parent -->
<div class="container">
  <div {@attach draggable([bounds(BoundsFrom.parent())])}>
    Contained child
  </div>
</div>

BoundsFrom Utilities

Viewport Boundaries

<script>
  import { bounds, BoundsFrom } from '@neodrag/svelte';
</script>

<!-- Basic viewport bounds -->
<div {@attach draggable([bounds(BoundsFrom.viewport())])}>
  Stay in window
</div>

<!-- Viewport with padding -->
<div
  {@attach draggable([
    bounds(
      BoundsFrom.viewport({
        top: 20,
        left: 20,
        right: 20,
        bottom: 20,
      }),
    ),
  ])}
>
  20px padding from edges
</div>

Element-Specific Boundaries

<script>
  import { bounds, BoundsFrom } from '@neodrag/svelte';

  let container;
</script>

<div bind:this={container} class="boundary-container">
  <div
    {@attach draggable([bounds(() => BoundsFrom.element(container))])}
  >
    Bound to container
  </div>
</div>

<!-- Using selector -->
<div class="zone" id="drop-zone">
  <div
    {@attach draggable([bounds(BoundsFrom.selector('#drop-zone'))])}
  >
    Bound by selector
  </div>
</div>

Custom Boundary Functions

<script>
  import { draggable, bounds } from '@neodrag/svelte';

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

<div {@attach draggable([bounds(circularBounds)])}>
  Circular boundary
</div>

<div {@attach draggable([bounds(timeBounds)])}>Animated boundary</div>

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.