useMouse

대상 엘리먼트를 기준으로 마우스의 위치를 추적하는 훅입니다.

현재 스크린에서의 위치, 스크린 영역 내의 위치, 전체 문서에서의 위치, 대상 엘리먼트 기준 위치, 해당 엘리먼트의 위치를 제공합니다.

대상 엘리먼트가 없는 경우 상대적인 위치와 해당 엘리먼트의 위치는 제공되지 않습니다.

Code

🔗 실제 구현 코드 확인

Interface

typescript

interface CursorPosition {
  screenX: number | null;
  screenY: number | null;
  clientX: number | null;
  clientY: number | null;
  pageX: number | null;
  pageY: number | null;
  elementRelativeX: number | null;
  elementRelativeY: number | null;
  elementPositionX: number | null;
  elementPositionY: number | null;
}

function useMouse<T extends HTMLElement>(): {
  ref: React.RefObject<T | null>;
  position: CursorPosition;
}

Returns

Name	Type	Description
ref	React.RefObject<T | null>	마우스 위치를 추적할 대상 엘리먼트에 연결하는 ref
position	CursorPosition	마우스의 현재 위치 정보 객체
position.screenX	number | null	사용자 모니터 내 X좌표
position.screenY	number | null	사용자 모니터 내 Y좌표
position.clientX	number | null	스크린 영역 내 X좌표
position.clientY	number | null	스크린 영역 내 Y좌표
position.pageX	number | null	전체 문서 기준 X좌표
position.pageY	number | null	전체 문서 기준 Y좌표
position.elementRelativeX	number | null	대상 엘리먼트 기준 X좌표 (엘리먼트 없으면 null)
position.elementRelativeY	number | null	대상 엘리먼트 기준 Y좌표 (엘리먼트 없으면 null)
position.elementPositionX	number | null	대상 엘리먼트의 X좌표 (엘리먼트 없으면 null)
position.elementPositionY	number | null	대상 엘리먼트의 Y좌표 (엘리먼트 없으면 null)

Usage

typescript

import { useMouse } from '@modern-kit/react';

const Example = () => {
  const { ref, position } = useMouse<HTMLDivElement>();
  const boxStyle = useMemo(() => {
    return {
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      width: '500px',
      height: '500px',
      background: '#439966',
      fontSize: '2rem',
      color: '#fff',
    }
  }, []);

  return (
    <>
      <div ref={ref} style={boxStyle}>
        마우스를 움직여보세요.
      </div>
      <p>사용자 모니터 내 X좌표: {position.screenX}</p>
      <p>사용자 모니터 내 Y좌표: {position.screenY}</p>
      <p>스크린 영역 내 X좌표: {position.clientX}</p>
      <p>스크린 영역 내 Y좌표: {position.clientY}</p>
      <p>전체 문서 기준 X좌표: {position.pageX}</p>
      <p>전체 문서 기준 Y좌표: {position.pageY}</p>
      <p>대상 엘리먼트 기준 X좌표: {position.elementRelativeX}</p>
      <p>대상 엘리먼트 기준 Y좌표: {position.elementRelativeY}</p>
      <p>대상 엘리먼트의 X좌표: {position.elementPositionX}</p>
      <p>대상 엘리먼트의 Y좌표: {position.elementPositionY}</p>
    </>
  );
};

Example