useScrollDirection

@hua-labs/hua/framework

Pro

출시 예정

Pro 플랜 컴포넌트

곧 출시됩니다! 웨이팅리스트에 등록하고 소식을 받아보세요.

웨이팅리스트 등록

스크롤 방향 감지 — 스마트 헤더 숨김/표시용

설치

bash

npm install @hua-labs/hua

Import

tsx

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

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

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

기본 사용법

tsx

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

const { direction, scrollY, isScrollingUp, isScrollingDown } = useScrollDirection({
  threshold: 10, // Minimum scroll delta
  throttle: 100, // Throttle in ms
});

return (
  <header className={isScrollingDown ? 'hidden' : 'visible'}>
    {/* Header hides on scroll down, shows on scroll up */}
  </header>
);

라이브 데모

스크롤 위치

0px

스크롤 방향

none

헤더 상태

표시

스마트 헤더 데모

Smart Header↑ 위

콘텐츠 블록 1

콘텐츠 블록 2

콘텐츠 블록 3

콘텐츠 블록 4

콘텐츠 블록 5

콘텐츠 블록 6

콘텐츠 블록 7

콘텐츠 블록 8

콘텐츠 블록 9

콘텐츠 블록 10

↕ 스크롤하여 테스트

위

아래

API 레퍼런스

옵션

이름	타입	기본값	설명
threshold	number	10	스크롤 임계값 (픽셀)
throttle	number	100	스크롤 이벤트 스로틀 (밀리초)
targetRef	RefObject	window	대상 스크롤 컨테이너 ref (기본: window)
initialDirection	"up" \| "down" \| "none"	"none"	초기 방향 ('up' \| 'down' \| 'none')

반환값

이름	타입	설명
direction	"up" \| "down" \| "none"	스크롤 방향 ('up' \| 'down' \| 'none')
scrollY	number	현재 스크롤 Y 위치
isScrollingUp	boolean	위로 스크롤 중 여부
isScrollingDown	boolean	아래로 스크롤 중 여부
delta	number	마지막 스크롤 델타 값
progress	number	스크롤 진행률 (0~1)
mounted	boolean	클라이언트 마운트 여부

사용 사례

헤더 자동 숨김

스크롤 다운 시 헤더 숨김

FAB 버튼 표시

스크롤 후 플로팅 액션 버튼 표시

무한 스크롤

스크롤 하단 도달 시 데이터 로드

당겨서 새로고침

스크롤 상단에서 새로고침

useScrollToggle useSmoothScroll