Skip to main content

useIdle

사용자의 비활성(idle) 상태를 감지하는 커스텀 훅입니다.

지정된 시간 동안 사용자 활동이 없으면 idle 상태로 판단하며, 마우스 움직임, 키보드 입력, 터치 이벤트 등 다양한 사용자 활동을 감지합니다. 페이지 visibility 변경도 감지하여 탭이 다시 활성화되면 active 상태로 전환됩니다.


감지되는 사용자 활동

useIdle은 다음 이벤트들을 통해 사용자 활동을 감지합니다:

  • mousemove - 마우스 움직임
  • mousedown - 마우스 클릭
  • resize - 창 크기 변경
  • keydown - 키보드 입력
  • touchstart - 터치 시작
  • wheel - 마우스 휠/스크롤
  • visibilitychange - 탭 전환 (페이지가 다시 보일 때)

모든 이벤트는 500ms로 스로틀링되어 불필요한 이벤트 호출을 방지합니다.


활용 사례

  • 자동 로그아웃 기능
  • 화면 보호기 활성화
  • 사용자 활동 모니터링
  • 리소스 절약 (비활성 시 API 호출 중지)
  • 알림 시스템 (사용자가 돌아왔을 때 알림 표시)

Code

🔗 실제 구현 코드 확인

Interface

typescript
interface UseIdleProps {
timeout: number; // 비활성 상태로 간주되기까지의 시간(밀리초)
onIdle?: () => void; // idle 상태 진입 시 콜백
onActive?: () => void; // active 상태 진입 시 콜백
}
typescript
function useIdle({ timeout, onIdle, onActive }: UseIdleProps): boolean

Usage

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

const Example = () => {
const isIdle = useIdle({
timeout: 5000, // 5초 후 idle 상태
onIdle: () => {
console.log('사용자가 비활성 상태입니다');
},
onActive: () => {
console.log('사용자가 다시 활성 상태입니다');
}
});

return (
<div>
<p>현재 상태: {isIdle ? '😴 Idle' : '🟢 Active'}</p>
<p>5초간 마우스나 키보드 사용을 멈춰보세요!</p>
</div>
);
};

Example

현재 상태: 🟢 Active

Idle 전환 횟수: 0

Active 전환 횟수: 0

✨ 마우스 움직임, 키보드 입력, 스크롤 등으로 활동을 감지합니다

⏰ 3초간 아무 활동이 없으면 Idle 상태가 됩니다

🔄 탭을 바꿨다가 돌아와도 Active 상태로 전환됩니다