axis

Restrict movement to a single axis (x or y)

The axis plugin locks movement to horizontal (x) or vertical (y) direction. Perfect for sliders, scrollbars, or any UI requiring one-dimensional dragging.

axis('x'); // Only horizontal movement
axis('y'); // Only vertical movement
axis(null); // Free movement (removes constraint)

Basic Usage

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

function AxisExamples() {
  const horizontalRef = useRef<HTMLDivElement>(null);
  const verticalRef = useRef<HTMLDivElement>(null);
  const freeRef = useRef<HTMLDivElement>(null);

  useDraggable(horizontalRef, [axis('x')]);
  useDraggable(verticalRef, [axis('y')]);
  useDraggable(freeRef, [axis(null)]);

  return (
    <div>
      <div ref={horizontalRef}>Horizontal only</div>
      <div ref={verticalRef}>Vertical only</div>
      <div ref={freeRef}>Any direction</div>
    </div>
  );
}

Dynamic Axis Switching

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

function DynamicAxis() {
  const ref = useRef<HTMLDivElement>(null);
  const [currentAxis, setCurrentAxis] = useState<'x' | 'y'>('x');

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

  useDraggable(ref, () => [axisComp]);

  return (
    <div>
      <div ref={ref}>Currently locked to: {currentAxis} axis</div>
      <button
        onClick={() =>
          setCurrentAxis(currentAxis === 'x' ? 'y' : 'x')
        }
      >
        Switch to {currentAxis === 'x' ? 'Y' : 'X'} axis
      </button>
    </div>
  );
}

Real-World Examples

Horizontal Slider Component

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

function Slider() {
  const trackRef = useRef<HTMLDivElement>(null);
  const handleRef = useRef<HTMLDivElement>(null);
  const [value, setValue] = useState(50);

  const handleDrag = (data) => {
    if (trackRef.current) {
      const trackWidth = trackRef.current.offsetWidth;
      setValue(Math.round((data.offset.x / trackWidth) * 100));
    }
  };

  useDraggable(handleRef, [
    axis('x'),
    bounds(() => BoundsFrom.element(trackRef.current)),
    events({ onDrag: handleDrag }),
  ]);

  return (
    <div>
      <div ref={trackRef} className="track">
        <div ref={handleRef} className="handle" />
      </div>
      <p>Value: {value}%</p>
    </div>
  );
}

Split Pane Resizer

// Vertical divider for horizontal split
const plugins = [
  axis('x'),
  bounds(
    BoundsFrom.parent({
      left: 100, // Min pane width
      right: 100, // Min pane width
    }),
  ),
];

How It Works

The axis plugin modifies the proposed movement during dragging:

axis('x'): Sets proposed.y = null (no vertical movement)
axis('y'): Sets proposed.x = null (no horizontal movement)
axis(null): No changes (free movement)

This happens in the plugin’s drag hook, so other plugins receive the constrained movement values.

API Reference

function axis(value?: 'x' | 'y' | null | undefined): Plugin;

Parameters:

value - The axis to constrain movement to
- 'x' - Horizontal only
- 'y' - Vertical only
- null or undefined - No constraint

Returns: A plugin object for use with draggable.