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:

React: Uses useMemo with dependency tracking

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

import { useRef, useState } from 'react';
import { useDraggable, axis, useCompartment } from '@neodrag/react';

function App() {
  const ref = useRef(null);
  const [currentAxis, setCurrentAxis] = useState('x');

  const axisComp = useCompartment(
    () => axis(currentAxis),
    [currentAxis],
  );
  useDraggable(ref, () => [axisComp]);

  return (
    <div>
      <div ref={ref}>Drag me</div>
      <button onClick={() => setCurrentAxis('y')}>Switch Axis</button>
    </div>
  );
}

Multiple Compartments

Mix static plugins with reactive compartments:

import { useRef, useState } from 'react';
import {
  useDraggable,
  axis,
  grid,
  bounds,
  BoundsFrom,
  events,
  useCompartment,
} from '@neodrag/react';

function App() {
  const ref = useRef(null);
  const [currentAxis, setCurrentAxis] = useState('x');
  const [gridSize, setGridSize] = useState(20);
  const [enableBounds, setEnableBounds] = useState(false);

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

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

  useDraggable(ref, () => [
    ...staticPlugins,
    axisComp,
    gridComp,
    boundsComp,
  ]);

  return <div ref={ref}>Drag me</div>;
}

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:

// ✅ Good - dynamic values
const [userChoice, setUserChoice] = useState('x');
const [gridSize, setGridSize] = useState(20);
const axisComp = useCompartment(() => axis(userChoice), [userChoice]);
const gridComp = useCompartment(
  () => grid([gridSize, gridSize]),
  [gridSize],
);

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

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

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

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

Debugging Compartments

Common Issues

Compartment not updating:

// ❌ Wrong - missing dependency
const axisComp = useCompartment(() => axis(currentAxis), []);

// ✅ Correct - include dependency
const axisComp = useCompartment(
  () => axis(currentAxis),
  [currentAxis],
);

Debug Logging

Add logging to see when compartments update:

const axisComp = useCompartment(() => {
  console.log('Axis compartment updating:', currentAxis);
  return axis(currentAxis);
}, [currentAxis]);