fullpage-react-squirrel

React에서 GSAP를 사용하여 풀페이지 스크롤을 구현하는 간단한 방법을 제공하는 라이브러리입니다.

✨ 기능

• 마우스 휠 및 터치 이벤트를 통한 부드러운 풀페이지 스크롤
• GSAP를 기반으로 한 고성능 애니메이션
• 페이지 내 개별 요소에 대한 등장 애니메이션 지원
• 간단한 페이지 컨트롤러 UI 제공

💿 설치

npm install fullpage-react-squirrel

또는

yarn add fullpage-react-squirrel

🚀 사용법

import { useFullPage } from "fullpage-react-squirrel";
import PageController from "fullpage-react-squirrel/dist/components/page-controller"; // 컨트롤러 import

function App() {
  const { scope, scrollToSection, movePage, curPage, pageCnt } = useFullPage({
    duration: 600, // 애니메이션 지속 시간 (ms)
  });

  return (
    <main ref={scope}>
      {/* 페이지 컨트롤러 */}
      <PageController
        curPage={curPage}
        pageCnt={pageCnt}
        pageHandler={movePage}
      />

      {/* 첫 번째 페이지 */}
      <section ref={scrollToSection} data-page={0}>
        <h1 data-animate>첫 번째 페이지</h1>
        <p data-animate>안녕하세요!</p>
      </section>

      {/* 두 번째 페이지 */}
      <section ref={scrollToSection} data-page={1}>
        <h1 data-animate>두 번째 페이지</h1>
      </section>

      {/* 세 번째 페이지 */}
      <section ref={scrollToSection} data-page={2}>
        <h1 data-animate>세 번째 페이지</h1>
      </section>
    </main>
  );
}

export default App;

💅 CSS 스타일링

라이브러리가 올바르게 동작하려면 최소한의 CSS가 필요합니다. 각 페이지 섹션은 .fp-section 클래스를 가지게 되므로, 이 클래스를 기준으로 스타일을 적용하는 것이 좋습니다.

필수 CSS

/* 전체 페이지의 스크롤을 막고, 초기 렌더링 시 깜빡임을 방지합니다. */
body {
  overflow: hidden;
}

/* useFullpage 훅이 적용하는 .fp-section 클래스에 대한 스타일입니다. */
.fp-section {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  /* 모바일 브라우저의 동적 뷰포트 높이에 대응합니다. 훅에서 --vh 변수를 설정해 줍니다. */
  height: calc(var(--vh, 1vh) * 100);
  /* 섹션 내부의 콘텐츠가 화면보다 길 경우, 내부 스크롤을 허용합니다. */
  overflow-y: auto;
}

선택 CSS (PageController)

PageController 컴포넌트를 위한 스타일입니다. .active 클래스는 컴포넌트가 현재 페이지를 감지하여 자동으로 추가해 줍니다.

/* 페이지 컨트롤러 컨테이너 */
.fp-handler {
  position: fixed;
  z-index: 10;
  top: 50%;
  right: 30px;
  transform: translateY(-50%);
  display: flex;
  flex-direction: column;
  gap: 10px; /* 버튼 간격 */
}

/* 페이지 컨트롤러 버튼 (점) */
.fp-handler span {
  width: 12px;
  height: 12px;
  background-color: rgba(255, 255, 255, 0.5);
  border-radius: 50%;
  cursor: pointer;
  transition: background-color 0.3s;
}

/* 활성화된 페이지 버튼 (PageController가 자동으로 클래스 추가) */
.fp-handler span.active {
  background-color: white;
}

주요 컨셉

1. useFullPage(): 풀페이지 기능을 활성화하는 메인 훅입니다.
2. scope: 애니메이션의 범위가 될 최상위 컨테이너에 ref로 전달해야 합니다.
3. scrollToSection: 각 풀페이지 섹션(보통 <section> 태그)에 ref로 전달해야 합니다.
4. data-page: 각 섹션에 0부터 시작하는 페이지 번호를 지정합니다.
5. data-animate: 페이지가 활성화될 때 애니메이션을 적용할 요소에 이 속성을 추가합니다.

⚙️ API

useFullPage(options?)

| 이름 | 타입 | 설명 | | :---------------- | :--------------------------------------- | :---------------------------------------------------------------- | | scope | React.RefObject<HTMLElement> | 풀페이지 컨테이너의 ref입니다. | | curPage | number | 현재 활성화된 페이지의 인덱스입니다. | | pageCnt | number | 전체 페이지의 개수입니다. | | movePage | (pageNum: number) => void | 지정된 페이지로 이동하는 함수입니다. | | goToNextPage | () => void | 다음 페이지로 이동합니다. | | goToPrevPage | () => void | 이전 페이지로 이동합니다. | | scrollToSection | (el: HTMLElement \| null) => void | 각 페이지 섹션의 ref에 전달되어야 하는 콜백 함수입니다. |

Options

| 이름 | 타입 | 기본값 | 설명 | | :--------- | :------- | :----- | :------------------------------ | | duration | number | 600 | 페이지 전환 애니메이션 시간(ms) |

<PageController />

페이지 이동을 위한 기본 UI 컨트롤러입니다.

| Prop | 타입 | 필수 | 설명 | | :------------ | :-------------------------- | :--- | :-------------------------------------------- | | curPage | number | O | 현재 페이지 인덱스 (useFullPage 반환값) | | pageCnt | number | O | 전체 페이지 수 (useFullPage 반환값) | | pageHandler | (pageNum: number) => void | O | 페이지 이동 함수 (useFullPage의 movePage) |

📄 라이선스

MIT