useScratch

React sensor hook that tracks scratching/dragging gestures on an element with mouse and touch support.

Usage

Live Editor

function Demo() {
  const elementRef = useRef(null);
  const state = useScratch(elementRef, {
    onScratchStart: (s) => {
      console.log('Scratch started:', s);
    },
    onScratch: (s) => {
      console.log('Scratching:', s);
    },
    onScratchEnd: (s) => {
      console.log('Scratch ended:', s);
    },
  });

  return (
    <div style={{ padding: '20px' }}>
      <div
        ref={elementRef}
        style={{
          width: '300px',
          height: '200px',
          border: '1px solid var(--ifm-color-emphasis-300)',
          borderRadius: '8px',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          backgroundColor: state.isScratching ? 'var(--ifm-color-emphasis-200)' : 'var(--ifm-background-surface-color)',
          color: 'var(--ifm-color-content)',
          cursor: 'pointer',
          userSelect: 'none',
        }}
      >
        {state.isScratching ? 'Scratching...' : 'Click and drag to scratch'}
      </div>
      <div style={{ marginTop: '20px', fontFamily: 'monospace', fontSize: '12px', color: 'var(--ifm-color-content)' }}>
        <div><strong>isScratching:</strong> {state.isScratching ? 'true' : 'false'}</div>
        {state.x !== undefined && <div><strong>x:</strong> {Math.round(state.x)}</div>}
        {state.y !== undefined && <div><strong>y:</strong> {Math.round(state.y)}</div>}
        {state.dx !== undefined && <div><strong>dx:</strong> {Math.round(state.dx)}</div>}
        {state.dy !== undefined && <div><strong>dy:</strong> {Math.round(state.dy)}</div>}
      </div>
    </div>
  );
};

Result

Loading...

API

UseScratchState

Property	Description	Type	DefaultValue
isScratching	Whether scratching is in progress	boolean (Required)	-
start	Start timestamp	number	-
end	End timestamp	number	-
x	x coordinate relative to element	number	-
y	y coordinate relative to element	number	-
dx	Delta in x direction	number	-
dy	Delta in y direction	number	-
docX	x coordinate in document	number	-
docY	y coordinate in document	number	-
posX	Element x position in document	number	-
posY	Element y position in document	number	-
elH	Element height	number	-
elW	Element width	number	-
elX	Element x position	number	-
elY	Element y position	number	-

UseScratchOptions

Property	Description	Type	DefaultValue
disabled	Whether to disable	boolean	-
onScratch	Callback during scratching	(state: UseScratchState) => void	-
onScratchStart	Callback when scratching starts	(state: UseScratchState) => void	-
onScratchEnd	Callback when scratching ends	(state: UseScratchState) => void	-

useScratch

Returns

UseScratchState: Scratch state

Arguments

Argument	Description	Type	DefaultValue
target	Target element	BasicTarget<HTMLElement> (Required)	-
options	Options	UseScratchOptions | undefined	-

BasicTarget

export type BasicTarget<T extends TargetType = Element> = (() => TargetValue<T>) | TargetValue<T> | MutableRefObject<TargetValue<T>>;

TargetValue

type TargetValue<T> = T | undefined | null;

TargetType

type TargetType = HTMLElement | Element | Window | Document | EventTarget;