useGesture

@hua-labs/hua/motion

터치/마우스 제스처 감지 — 스와이프, 탭, 길게 누르기, 핀치 등

설치

bash

npm install @hua-labs/hua

Import

tsx

import { useGesture } from "@hua-labs/hua/framework";

@hua-labs/motion-core의 모션 훅을 @hua-labs/hua/framework에서 통합 제공합니다.

UI 컴포넌트, 모션 훅, i18n을 하나의 패키지로 사용할 수 있습니다.

기본 사용법

tsx

const gesture = useGesture({
  onSwipe: (direction) => console.log('Swiped:', direction),
  onTap: (x, y) => console.log('Tapped at:', x, y),
});

return (
  <div
    onTouchStart={gesture.onTouchStart}
    onTouchMove={gesture.onTouchMove}
    onTouchEnd={gesture.onTouchEnd}
    onMouseDown={gesture.onMouseDown}
    onMouseMove={gesture.onMouseMove}
    onMouseUp={gesture.onMouseUp}
  >
    Touch or click me
  </div>
);

라이브 데모

제스처를 시험해보세요

스와이프, 탭, 또는 길게 누르세요

터치 또는 마우스 드래그

마지막 제스처

-

탭 횟수

0

활성

No

지원되는 제스처

스와이프

네 방향으로 스와이프 감지

탭

단일 탭 감지

더블 탭

두 번 빠르게 탭

길게 누르기

길게 누르면 트리거됨

팬

드래그 방향 추적

핀치

두 손가락 줌 감지

회전

두 손가락 회전 감지

API 레퍼런스

옵션

이름	타입	기본값	설명
enabled	boolean	true	docs:hooks.use-gesture.options.enabled
threshold	number	10	docs:hooks.use-gesture.options.threshold
timeout	number	300	docs:hooks.use-gesture.options.timeout
swipeThreshold	number	50	docs:hooks.use-gesture.options.swipeThreshold
swipeVelocity	number	0.3	docs:hooks.use-gesture.options.swipeVelocity
onSwipe	(direction, distance, velocity) => void	-	docs:hooks.use-gesture.options.onSwipe
onPinch	(scale, delta) => void	-	docs:hooks.use-gesture.options.onPinch
onRotate	(angle, delta) => void	-	docs:hooks.use-gesture.options.onRotate
onPan	(deltaX, deltaY, totalX, totalY) => void	-	docs:hooks.use-gesture.options.onPan
onTap	(x, y) => void	-	docs:hooks.use-gesture.options.onTap
onDoubleTap	(x, y) => void	-	docs:hooks.use-gesture.options.onDoubleTap
onLongPress	(x, y) => void	-	docs:hooks.use-gesture.options.onLongPress

반환값

이름	타입	설명
isActive	boolean	docs:hooks.use-gesture.returns.isActive
gesture	string \| null	docs:hooks.use-gesture.returns.gesture
scale	number	docs:hooks.use-gesture.returns.scale
rotation	number	docs:hooks.use-gesture.returns.rotation
deltaX	number	docs:hooks.use-gesture.returns.deltaX
deltaY	number	docs:hooks.use-gesture.returns.deltaY
distance	number	docs:hooks.use-gesture.returns.distance
velocity	number	docs:hooks.use-gesture.returns.velocity
onTouchStart	(e: TouchEvent) => void	docs:hooks.use-gesture.returns.onTouchStart
onTouchMove	(e: TouchEvent) => void	docs:hooks.use-gesture.returns.onTouchMove
onTouchEnd	(e: TouchEvent) => void	docs:hooks.use-gesture.returns.onTouchEnd
onMouseDown	(e: MouseEvent) => void	docs:hooks.use-gesture.returns.onMouseDown
onMouseMove	(e: MouseEvent) => void	docs:hooks.use-gesture.returns.onMouseMove
onMouseUp	(e: MouseEvent) => void	docs:hooks.use-gesture.returns.onMouseUp
start	() => void	docs:hooks.use-gesture.returns.start
stop	() => void	docs:hooks.use-gesture.returns.stop
reset	() => void	docs:hooks.use-gesture.returns.reset

다중 제스처 예시

tsx

const gesture = useGesture({
  onSwipe: (direction) => {
    if (direction === 'left') goToNext();
    if (direction === 'right') goToPrev();
  },
  swipeThreshold: 80,
});

// Current gesture state
console.log(gesture.gesture);  // "swipe-left"
console.log(gesture.velocity); // 1.5

사용 사례

드래그 앤 드롭

터치/마우스 기반 요소 이동

줌 가능한 콘텐츠

핀치 줌 인터랙션

스와이프 가능한 UI

스와이프로 카드/항목 탐색

인터랙티브 UI

제스처 기반 인터랙티브 컴포넌트

useSmoothScroll useMouse