useDial

A custom react hook that registers dragging and mouse wheel actions and returns an angle representing a rotation of the target element relative to the origin.

This custom hook allows for creating UI elements such as knobs and dials that can be adjusted by dragging or using the mouse wheel.

This hook registers dragging actions from the user of the targetRef element, and also handles adjusting the dial through rotating the mouse wheel or dragging vertically when the pointer is over the dragAreaRef element.

The hook will use the position of the pointer while dragging to calculate an angle relative to an origin (which is the center of rotation).

Example: A Volume Dial

This is all much easier to show than to describe, so here is a full example that models a volume dial that goes from 0-11. The user can change the volume by rotating the knob, using the mouse wheel, or dragging vertically in the component’s area.

Demo

VolumeDial component

VolumeDial.tsx

import { useRef } from "react";
import { useDial, TAU, rad2deg } from "@gertalot/sliders";
import VolumeDialTicks from "./VolumeDialTicks";

/**
 * A component that renders a circular volume dial in an SVG, with tick marks. The volume
 * can be adjusted from 0-11.
 */
const VolumeDial = () => {
  // The dragArea is a div enclosing the volume dial. This allows for mouse wheel rotations or
  // vertical draggin on the whole area of the component.
  const dragAreaRef = useRef<HTMLDivElement>(null);
  const targetRef = useRef<SVGCircleElement>(null);

  // The limits of rotation. `TAU` is defined as `2*Math.PI` and is a useful shorthand when
  // working with radians. 3/8 TAU is roughly "7 o'clock", 9/8 TAU is roughly "5 o'clock".
  // This corresponds to a volume from 0-11.
  const props = { minAngle: (3 / 8) * TAU, maxAngle: (9 / 8) * TAU, minValue: 0, maxValue: 11 };

  // We use various radii, for the ticks, the dial, and the volume numbers, for example. They are
  // all relative to the `radius` value.
  const radius = 0.9;

  const { angle, value } = useDial({
    ...props,
    dragAreaRef,
    targetRef,
    value: 6,
  });

  return (
    <>
      <div className="w-full h-64 mt-0 flex items-center justify-center touch-none select-none" ref={dragAreaRef}>
        <svg width="250" height="250" viewBox="-1 -1 2 2">
          {/* Draw the circle with the triangle indicating the value and rotate both to point
              the right way */}
          <g transform={`rotate(${rad2deg(angle)}, 0, 0)`} ref={targetRef}>
            <circle
              style={{ stroke: "var(--sl-color-accent" }}
              className="fill-slate-600"
              cx={0}
              cy={0}
              r={radius * 0.6}
              strokeWidth="0.01"
            />
            <path
              style={{ fill: "var(--sl-color-accent" }}
              className="stroke-nonee"
              d={`M ${radius * 0.55} 0 L ${radius * 0.4} -0.05 L ${radius * 0.4} 0.05 L ${radius * 0.55} 0`}
            />
          </g>
          {/* Show the volume as a number in the center of the dial */}
          <text
            x={0}
            y={0}
            textAnchor="middle"
            dominantBaseline="middle"
            fontSize="0.3"
            fontFamily="monospace"
            fontWeight="bold"
            fill="var(--sl-color-accent"
            style={{ color: "var(--sl-color-accent" }}
          >
            {value!.toFixed(0)}
          </text>
          {/* A separate component draws the tick marks around the dial */}
          <VolumeDialTicks {...props} radius={radius} />
        </svg>
      </div>
    </>
  );
};

export default VolumeDial;

VolumeDialTicks component

VolumeDialTicks.tsx

import { useMemo } from "react";
import { valueToAngle, angleToPoint } from "@gertalot/sliders";

/**
 * Draw tick marks and numbers to indicate volume around the dial
 */
const VolumeDialTicks = ({
  minAngle,
  maxAngle,
  minValue,
  maxValue,
  radius,
}: {
  minAngle: number;
  maxAngle: number;
  minValue: number;
  maxValue: number;
  radius: number;
}) => {
  return useMemo(() => {
    const ticks = [];
    for (let i = 0; i <= 11; i++) {
      const angle = valueToAngle(i, minValue, maxValue, minAngle, maxAngle);
      const posFrom = angleToPoint(angle, { x: 0, y: 0 }, radius * 0.7);
      const posTo = angleToPoint(angle, { x: 0, y: 0 }, radius * 0.8);
      const posLabel = angleToPoint(angle, { x: 0, y: 0 }, radius * 0.9);
      ticks.push(
        <g key={`main-${i}`}>
          <line
            x1={posFrom.x}
            y1={posFrom.y}
            x2={posTo.x}
            y2={posTo.y}
            strokeWidth={0.01}
            strokeLinecap="round"
            // the `--sl-color-accent` variables come from the Astro Starlight theme
            // that is used to generate this site
            style={{ stroke: "var(--sl-color-accent" }}
          />
          <text
            x={posLabel.x}
            y={posLabel.y}
            textAnchor="middle"
            dominantBaseline="middle"
            fontSize="0.11"
            fill="var(--sl-color-accent"
            style={{ color: "var(--sl-color-accent" }}
          >
            {i}
          </text>
        </g>,
      );
    }
    for (let i = 0; i <= 11; i += 0.2) {
      const angle = valueToAngle(i, minValue, maxValue, minAngle, maxAngle);
      const posFrom = angleToPoint(angle, { x: 0, y: 0 }, radius * 0.7);
      const posTo = angleToPoint(angle, { x: 0, y: 0 }, radius * 0.72);
      ticks.push(
        <g key={`small-${i}`}>
          <line
            x1={posFrom.x}
            y1={posFrom.y}
            x2={posTo.x}
            y2={posTo.y}
            strokeWidth={0.01}
            strokeLinecap="round"
            style={{ stroke: "var(--sl-color-accent" }}
          />
        </g>,
      );
    }
    return <g>{ticks}</g>;
  }, [maxAngle, maxValue, minAngle, minValue]);
};

export default VolumeDialTicks;

Usage

const {
  isRotating, // true if the user is rotating
  isOnTarget, // true if the pointer is over the target
  angle, // the angle of rotation, 0-2π
  fullRotations, // the number of full rotations
  totalAngle, // the total angle, including full rotations
  value, // the value corresponding to the angle
} = useDial({
  dragAreaRef, // the element that functions as the "active" area
  targetRef, // the target element that is rotated
  origin, // a point or a function returning a point - the center of rotation
  minAngle, // minimum allowed angle
  maxAngle, // maximum allowed angle
  minValue, // minimum value - corresponds with minAngle
  maxValue, // maximum value - corresponds with maxAngle
  value, // initial value
});

Props

This hook accepts a few different combinations of props (the valid combinations are described in types so if your editor is set up to autocomplete based on type it will help you).

Basic props

In its most basic form, this hook allows for infitie rotations clockwise or counterclockwise, and will return just the angle (in radians from 0-2π, where 0 is “3 o’clock”), and the total angle (in radians, but taking into account the number of full rotations). The props are:

dragAreaRef

(required) the element that is “active”, i.e. the hook’s event listeners will register mouse wheel rotation and vertical dragging actions when the pointer is over this element.

targetRef

(required) the target element that can be dragged around an origin

origin

This optional prop should, when specified, be either a point or a function. When specified as a point of type Point2D, they are the {x,y} coordinates of the center of rotation, _relative to the dragAreaRef element’s bounding rect. When a function is passed, the function will be called when the dragAreaRef changes size, and can be used to dynamically change the center of rotation. If origin is not specified, it will be dynamically set to the center of the dragAreaRef element.

Limit angle range

The second form takes the basic props described above, and allows the following in addition:

minAngle, maxAngle

specifies the minimum and maximum allowed angles of rotation. If the user tries to drag past these angles, the angle will be clamped to the minimum or maximum angle.

angle

optionally specify the initial angle that the hook should use. If not specified, uses minAngle. Note: if no angles are specified at all, the initial angle will be 0.

Map rotation to values

The most complete set of props linearly map an angle of rotation to a value, and this is probably the most likely way you’ll use this hook. The “volume knob” example below uses these props, to limit the possible angles to betwee “7 o’clock” and “5 o’clock” (going clockwise), and map the angle to a value between 0-11. You specify the following:

• minAngle and maxAngle as above;

minValue, maxValue

the minimum and maximum values. These correspond to the minimum and maximum angles.

value

an optional initial value, which will be mapped to the corresponding angle. If not specified, the minimum value will be used.

Returns

This custom hook returns an object with the following properties:

isRotating

true if the user is actively rotating the dial, either through dragging the target, using the mouse wheel, or dragging vertically on the dragAreaRef element.

isOnTarget

true if the pointer is currently over the targetRef element.

angle

the angle of rotation, between 0-2π, where 0 is “3 o’clock” and values increase clockwise. This can be used to position the target element, transform elements, or otherwise indicate the angle of rotation visually.

fullRotations

the number of full, 360° rotations the user has made. This starts at 0, and clockwise rotations will be positive, anti-clockwise is negative.

totalAngle

this is the total angle, taking full rotations into account.

value

the mapped value, if minValue, maxValue, minAngle, and maxAngle were specified in the props.