Compartment

Using compartments to create isolated plugin environments

Compartments are Neodrag v3’s solution for reactive plugin updates. They provide manual, predictable control over when your draggable behavior changes.

What Are Compartments?

Compartments are reactive containers that hold a single plugin (or null) and update when their dependencies change.

Key Rule: One plugin per compartment - they don’t hold arrays of plugins.

How They Work

Compartments wrap your framework’s reactive system:

Vue: Uses watchEffect with immediate execution

Why Compartments?

V2 had automatic reactivity but caused problems:

Performance Issues: Entire plugin arrays recreated on every change
Memory Leaks: Old plugin instances weren’t properly cleaned up
Unpredictable Updates: Hard to control when updates happened
Over-Engineering: Simple static configs got reactive treatment they didn’t need

Compartments solve this with manual control, predictable updates, and better performance.

Basic Usage

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

const currentAxis = ref('x');
const axisComp = useCompartment(() => axis(currentAxis.value));
</script>

<template>
  <div>
    <div v-draggable="() => [axisComp]">Drag me</div>
    <button @click="currentAxis = 'y'">Switch Axis</button>
  </div>
</template>

Multiple Compartments

Mix static plugins with reactive compartments:

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

const currentAxis = ref('x');
const gridSize = ref(20);
const enableBounds = ref(false);

// Reactive compartments
const axisComp = useCompartment(() => axis(currentAxis.value));
const gridComp = useCompartment(() =>
  grid([gridSize.value, gridSize.value]),
);
const boundsComp = useCompartment(() =>
  enableBounds.value ? bounds(BoundsFrom.parent()) : null,
);

// Static plugins (never change)
const staticPlugins = [events({ onDrag: console.log })];
</script>

<template>
  <div
    v-draggable="
      () => [...staticPlugins, axisComp, gridComp, boundsComp]
    "
  >
    Drag me
  </div>
</template>

When to Use Compartments

Use Compartments For:

Dynamic values that change from user interaction (sliders, dropdowns, toggles)
Conditional plugin logic (enable/disable features based on state)
Complex computed values with multiple dependencies

Don’t Use Compartments For:

Static values that never change (just use direct plugin arrays)
Simple boolean toggles (use direct conditionals instead)

Examples:

<script setup>
// ✅ Good - dynamic values
const userChoice = ref('x');
const gridSize = ref(20);
const axisComp = useCompartment(() => axis(userChoice.value));
const gridComp = useCompartment(() =>
  grid([gridSize.value, gridSize.value]),
);

// ❌ Bad - static values
const staticComp = useCompartment(() => bounds(BoundsFrom.parent()));

// ✅ Better - direct usage
const staticPlugins = [bounds(BoundsFrom.parent())];

// ❌ Bad - simple boolean
const showGrid = ref(false);
const simpleComp = useCompartment(() =>
  showGrid.value ? grid([10, 10]) : null,
);

// ✅ Better - direct conditional
const plugins = () => [
  axis('x'),
  ...(showGrid.value ? [grid([10, 10])] : []),
];
</script>

Debugging Compartments

Common Issues

Compartment not updating:

<script setup>
const currentAxis = ref('x');

// ❌ Wrong - not reactive
const axisComp = useCompartment(() => axis('x'));

// ✅ Correct - reactive reference
const axisComp = useCompartment(() => axis(currentAxis.value));
</script>

Debug Logging

Add logging to see when compartments update:

<script setup>
const axisComp = useCompartment(() => {
  console.log('Axis compartment updating:', currentAxis.value);
  return axis(currentAxis.value);
});
</script>