ScrollMagic - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #llm #go #android #linux #docker #macos #nodejs #awesome #cli #pytorch #security #openai

ScrollMagic

(★ 14,956)

마법 같은 스크롤 인터랙션을 위한 JavaScript 라이브러리입니다.

파일 탐색기

최종 버전 다운로드 (.zip)

- banner.txt
- - contain.html
  - intersect.html
  - shared.css
- export-diagrams.mjs
- - agnosticValues.ts
  - getScrollContainerDimensions.ts
  - getScrollPos.ts
  - pickDifferencesFlat.ts
  - processProperties.ts
  - rafQueue.ts
  - registerEvent.ts
  - sanitizeProperties.ts
  - sharedResizeObserver.ts
  - throttleRaf.ts
  - transformers.ts
  - transformObject.ts
  - typeguards.ts
- Container.ts
- ContainerProxy.ts
- env.d.ts
- EventDispatcher.ts
- ExecutionQueue.ts
- index.ts
- Options.processors.ts
- Options.ts
- ScrollMagic.ts
- ScrollMagicError.ts
- ScrollMagicEvent.ts
- util.ts
- ViewportObserver.ts
- - caching.test.ts
  - containers.test.ts
  - destroy.test.ts
  - dev-warnings.test.ts
  - element-tracking.test.ts
  - enable-disable.test.ts
  - helpers.ts
  - refresh.test.ts
  - scroll-progress.test.ts
  - scroll-velocity.test.ts
  - UNTESTED-KNOWN-BUGS.md
- - agnosticValues.test.ts
  - ContainerProxy.test.ts
  - EventDispatcher.test.ts
  - ExecutionQueue.test.ts
  - getScrollContainerDimensions.test.ts
  - getScrollPos.test.ts
  - Options.processors.test.ts
  - pickDifferencesFlat.test.ts
  - processProperties.test.ts
  - rafQueue.test.ts
  - registerEvent.test.ts
  - sanitizeProperties.test.ts
  - ScrollMagicError.test.ts
  - ScrollMagicEvent.test.ts
  - sharedResizeObserver.test.ts
  - throttleRaf.test.ts
  - transformers.test.ts
  - transformObject.test.ts
  - typeguards.test.ts
.gitignore
.prettierignore
CHANGELOG.md
eslint.config.mjs
LICENSE.md
MAINTAINING.md
package-lock.json
package.json
PLUGINS.md
prettier.config.mjs
README.md
ROADMAP.md
rollup.config.mjs
tsconfig.json
typedoc.json
vitest.config.ts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ScrollMagic 3
[![npm version](https://img.shields.io/npm/v/scrollmagic/next)](https://www.npmjs.com/package/scrollmagic/v/next)
[![license](https://img.shields.io/badge/license-MIT-lightgrey)](https://raw.githubusercontent.com/janpaepke/ScrollMagic/main/LICENSE.md)
[![bundle size](https://img.shields.io/badge/gzip-~6kb-brightgreen)](https://bundlephobia.com/package/scrollmagic)
[![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://npmgraph.js.org/?q=scrollmagic)
[![TypeScript](https://img.shields.io/badge/TypeScript-native-blue)](https://www.typescriptlang.org/)
### 마법 같은 스크롤 인터랙션을 위한 경량 라이브러리
> \*\*ScrollMagic v2를 찾고 계시나요?\*\* 레거시 버전은 [`v2-stable`](https://github.com/janpaepke/ScrollMagic/tree/v2-stable) 브랜치에 있습니다.
ScrollMagic은 사용자가 스크롤할 때 뷰포트를 기준으로 요소의 위치를 파악하고, 그 위치가 변경될 때벤트를 발생시킵니다.
이 라이브러리는 [IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver)와 [ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)를 감싸 만든 편리한 래퍼(wrapper)로, 성능 저하 요인과 직관적이지 않은 예외 케이스들을 알아서 처리해 줍니다.
[![Donate](https://scrollmagic.io/assets/img/btn\_donate.svg 'Shut up and take my money!')](https://www.paypal.com/cgi-bin/webscr?cmd=\_s-xclick&hosted\_button\_id=8BJC8B58XHKLL 'Shut up and take my money!')
### 애니메이션 라이브러리가 아닙니다 – 원하신다면 그렇게 쓸 수도 있지만요.
ScrollMagic 자체는 어떤 애니메이션도 실행하지 않습니다. 정밀한 스크롤 위치 데이터와 이벤트만 제공할 뿐이며, 이를 어떻게 활용할지는 온전히 개발자의 몫입니다. 완성된 스크롤 애니메이션 솔루션을 찾고 계신다면 [GSAP ScrollTrigger](https://gsap.com/docs/v3/Plugins/ScrollTrigger/), [Motion](https://motion.dev/docs/scroll), 또는 [anime.js](https://animejs.com/)를 확인해 보세요.
순수 CSS 기반 스크롤 애니메이션의 경우, 네이티브 [scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS\_scroll-driven\_animations)를 참고하세요(아직 모든 브라우저에서 지원되지는 않습니다). ScrollMagic은 네이티브 API가 커버하지 못하는 크로스 브라우저 지원, 이벤트 콜백, 진행률(progress) 값, 상태 관리 기능을 제공하여 이를 보완합니다.
ScrollMagic은 스크롤 기반 UX를 위한 범용적이고, 프레임워크에 구애받지 않으며, 의존성이 없는 기초 라이브러리입니다. 클래스 토글, 애니메이션, 지연 로딩(lazy loading), 패럴랙스, 스크롤 연동 비디오, 사용자 행동 추적 등 무엇에든 활용할 수 있습니다.
### 왜 ScrollMagic인가요?
- 초경량 용량, 제로 의존성
- 무료 사용 ([오픈 소스](LICENSE.md))
- 성능 최적화 (공유 옵저버, 일괄 처리된 rAF, 단일 프레임 업데이트)
- 모던 브라우저용 제작, 모바일 호환
- 네이티브 TypeScript 지원
- SSR 안전성 보장
- 모든 스크롤 컨테이너와 호환 (윈도우 또는 커스텀 요소)
- 가로 및 세로 스크롤 지원
- 확장성을 위한 플러그인 시스템
- 프레임워크 독립적 — React, Vue, 바닐라 JS 등 무엇이든 연동 가능
## 설치하기
```sh
npm install scrollmagic@next
```
## 빠른 시작
```js
import ScrollMagic from 'scrollmagic';
new ScrollMagic({ element: '#my-element' })
.on('enter', () => console.log('visible!'))
.on('leave', () => console.log('gone!'))
.on('progress', e => console.log(`${(e.target.progress \* 100).toFixed(0)}%`));
```
## 작동 방식
ScrollMagic은 활성 범위를 정의하기 위해 두 가지 경계 세트를 사용합니다.
- \*\*컨테이너 경계 (Container bounds)\*\* — `containerStart`와 `containerEnd`로 정의되는 스크롤 컨테이너상의 영역
- \*\*요소 경계 (Element bounds)\*\* — `elementStart`와 `elementEnd`로 정의되는 추적 대상 요소상의 영역
요소 경계가 컨테이너 경계를 통과함에 따라 진행률(progress)이 `0`에서 `1`까지 이동합니다. 진입(enter), 이탈(leave), 진행률 변경 시 이벤트가 발생합니다.
### 포함(Contain)과 교차(Intersect)
가장 일반적인 두 가지 설정은 \*\*포함(contain)\*\*과 \*\*교차(intersect)\*\*입니다. 이 둘의 차이는 컨테이너 경계가 배치되는 위치에 있습니다.
#### 포함 모드 (`element`가 `null`일 때의 기본값)
![Contain mode animation: tall element scrolls through viewport, progress tracks from 0% to 100%](docs/dist/gfx/

contain.gif)
컨테이너 경계가 뷰포트 가장자리와 일치합니다. 즉, `containerStart`와 `containerEnd` 모두 `'here'`(`0%`)에 위치합니다. 한쪽이 다른 쪽을 완전히 \*\*포함(contain)\*\*하는 동안 진행률은 0에서 1까지 변화합니다: 요소가 뷰포트 내에 완전히 보이거나, 요소가 뷰포트를 완전히 가리는 경우입니다.
일반적인 용도: 스크롤 진행률 바, 패럴랙스, 스크롤 연동 비디오, 스크롤 기반 스토리텔링.
  
#### Intersect (`element`가 설정된 경우의 기본값)
![Intersect 모드 애니메이션: 요소가 뷰포트를 스크롤하며 지나갈 때, 진행률이 0%에서 100%까지 추적됨](docs/dist/gfx/intersect.gif)
컨테이너 경계가 전체 뷰포트에 걸쳐 확장됩니다. 즉, `containerStart`와 `containerEnd`가 `'opposite'` 가장자리(`100%`)에 위치합니다. 요소가 뷰포트와 \*\*교차(intersect)\*\*하는 동안 진행률은 0에서 1까지 변화합니다. 이는 요소의 앞쪽 가장자리가 진입할 때 시작하여 뒤쪽 가장자리가 나갈 때 끝납니다.
일반적인 용도: 진입/이탈 애니메이션, 지연 로딩, 클래스 토글, 가시성 추적.
  
#### 기본값만이 아닙니다
\_contain\_과 \_intersect\_는 유추되는 기본값이지만, 명시적으로 설정할 수도 있습니다. 예를 들어, contain 동작을 얻기 위해 요소가 있는 인스턴스에 `containerStart: 0, containerEnd: 0`을 설정하거나, 사용자 정의 추적 영역을 위해 컨테이너와 요소의 인셋을 혼합할 수 있습니다. 이 두 가지 설정은 \*\*엄격한 모드가 아니라 유용한 사고 모델\*\*입니다.
#### 네이티브 스크롤 기반 애니메이션 범위
[CSS scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS\_scroll-driven\_animations)에 익숙하다면, 네이티브 `view()` 타임라인 범위가 ScrollMagic 설정과 어떻게 매핑되는지 확인하세요:
| 네이티브 범위 | ScrollMagic 대응 값 |
| ------------ | ---------------------- |
| `cover` | \_intersect\_ 기본값 — `containerStart: 'opposite', containerEnd: 'opposite'` |
| `contain` | \_contain\_ 기본값 — `containerStart: 0, containerEnd: 0` |
| `entry` | `containerStart: 'opposite', containerEnd: 0` — 컨테이너 영역이 뒤쪽 가장자리로 축소됨 |
| `exit` | `containerStart: 0, containerEnd: 'opposite'` — 컨테이너 영역이 앞쪽 가장자리로 축소됨 |
네이티브 `entry-crossing`과 `exit-crossing` 범위는 위의 `entry` 및 `exit`와 동일합니다. 이 구분은 단일 네이티브 타임라인을 세분화할 때만 적용되며, 독립형 추적 범위를 정의할 때는 적용되지 않습니다.
## 옵션
모든 옵션은 선택 사항입니다. 생성자에 전달할 수 있으며, 세터(setter)나 `.modify()`를 통해 언제든지 업데이트할 수 있습니다.
| 옵션 | 타입 | 기본값 | 설명 |
| ---------------- | -------------------------------------- | -------------------------- | ----------------------------------------------------- |
| `element` | `Element \| string \| null` | `container`의 첫 번째 자식 | 추적할 요소 (또는 CSS 셀렉터). 셀렉터는 첫 번째 요소만 일치시킵니다. 여러 개를 추적하려면 요소당 하나의 인스턴스를 생성하세요. |
| `elementStart` | `number \| string \| function` | `0` | 요소의 시작 \*\*인셋(inset)\*\*. |
| `elementEnd` | `number \| string \| function` | `0` | 요소의 끝 \*\*인셋(inset)\*\*. |
| `container` | `Window \| Element \| string \| null` | `window` | 스크롤 컨테이너 (또는 CSS 셀렉터). 셀렉터는 첫 번째 일치 항목을 사용합니다. |
| `containerStart` | `number \| string \| function \| null` | 유추됨 (아래 참조) | 스크롤 컨테이너의 시작 \*\*인셋(inset)\*\*. |
| `containerEnd` | `number \| string \| function \| null` | 유추됨 (아래 참조) | 스크롤 컨테이너의 끝 \*\*인셋(inset)\*\*. |
| `vertical` | `boolean` | `true` | 스크롤 축. `true` = 수직, `false` = 수평. |
\*\*인셋 값(Inset values)\*\*은 CSS의 `top`/`bottom`과 같이 작동합니다. 양수 값은 추적된 방향의 각 가장자리 안쪽으로 오프셋을 적용합니다. 허용되는 값 유형:
- \*\*숫자(Numbers)\*\* — 픽셀 값 (예: `50`)
- \*\*문자열(Strings)\*\* — 백분율 또는 픽셀 문자열 (예: `'50%'`, `'20px'`), 부모 크기 기준 (컨테이너 옵션의 경우 스크롤 컨테이너, 요소 옵션의 경우 요소 기준)
- \*\*이름이 지정된 위치(Named positions)\*\* — `'here'` (0%), `'center'` (50%), `'opposite'` (100%)
- \*\*함수(Functions)\*\* — 동적 계산을 위한 `(size) => number`
\*\*`null`

infer로 설정: `element`, `container`, `containerStart`, 또는 `containerEnd`의 값을 `null`로 설정하면 추론된 기본값으로 재설정됩니다.
`containerStart`/`containerEnd`의 경우 추론되는 값은 `element`에 따라 다릅니다:
- \*\*`element`가 `null`인 경우\*\* → [\*\*contain\*\*](#contain-default-when-element-is-null) 기본값으로 설정됨: 요소가 컨테이너의 첫 번째 자식으로 추론되며 (`window`의 경우 `document.body`), 컨테이너 오프셋은 `'here'` (0%)가 되어 진행 상황을 전체 스크롤 위치에 매핑합니다.
- \*\*`element`가 `null`이 아닌 경우\*\* → [\*\*intersect\*\*](#intersect-default-when-element-is-set) 기본값으로 설정됨: 컨테이너 오프셋은 `'opposite'` (100%)이 되어 요소가 전체 뷰포트를 통과하며 스크롤될 때 이를 추적합니다.
## 이벤트
`.on()`, `.off()`, 또는 `.subscribe()`를 사용하여 구독하세요 (구독 취소 함수를 반환합니다). 첫 번째 호출 후 리스너를 자동으로 제거하려면 `{ once: true }`를 전달하세요. 리스너가 이미 제거된 후(예: `once` 리리스너가 실행된 후) `.off()`나 구독 취소 함수를 호출하는 것은 안전한 no-op(동작 없음)입니다.
| 이벤트 | 시점 |
| ---------- | -------------------------------------------------------- |
| `enter` | 요소가 활성 영역에 진입할 때 (진행도가 0 또는 1에서 벗어남) |
| `leave` | 요소가 활성 영역을 벗어날 때 (진행도가 0 또는 1에 도달함) |
| `progress` | 활성 영역 내에서 진행도 값이 변경될 때 |
모든 이벤트는 다음을 제공합니다:
```ts
event.target; // the ScrollMagic instance (access all properties, e.g. event.target.progress, event.target.element)
event.type; // 'enter' | 'leave' | 'progress'
event.direction; // 'forward' | 'reverse'
event.location; // 'start' | 'inside' | 'end'
```
## 예시
```js
// Intersect (default): active while any part of the element
// is visible in the viewport
new ScrollMagic({
element: '#a',
});
// Intersect with narrowed container zone:
// active while the element passes through the center line
new ScrollMagic({
element: '#b',
containerStart: 'center',
containerEnd: 'center',
});
// Same as above, but with element offsets:
// starts 50px before the element, ends 100px after it
new ScrollMagic({
element: '#c',
containerStart: 'center',
containerEnd: 'center',
elementStart: -50,
elementEnd: -100,
});
// Fixed scroll distance of 150px, regardless of element height.
// elementEnd receives the element's size and offsets from
// the bottom — (size - 150) leaves only 150px of track.
new ScrollMagic({
element: '#d',
containerStart: 'center',
containerEnd: 'center',
elementEnd: size => size - 150,
});
// Contain: active only while the element is fully visible
// (element insets pushed to opposite edges = full element height)
new ScrollMagic({
element: '#e',
elementStart: 'opposite', // same as '100%'
elementEnd: 'opposite', // same as '100%'
});
// Contain (default when no element): track overall scroll progress
new ScrollMagic();
```
## API
```ts
const sm = new ScrollMagic(options);
// Event listeners
sm.on(type, callback); // add listener, returns instance (chainable)
sm.on(type, callback, { once: true }); // listener auto-removes after first invocation
sm.off(type, callback); // remove listener, returns instance (chainable)
sm.subscribe(type, callback); // add listener, returns unsubscribe function
sm.subscribe(type, callback, { once: true }); // both auto-removes and returns unsubscribe
// Modify options after creation
sm.modify({ containerStart: 'center' });
// All options can also be directly read and written
const elem = sm.element; // get the tracked element
sm.containerStart = 'center'; // set individual options
// Read-only getters
sm.progress; // 0–1, how far through the active zone
sm.activeRange; // { start, end } container scroll positions where tracking is active
sm.scrollVelocity; // px/s along tracked axis, 0 when idle
sm.resolvedBounds; // { element, container } cached layout bounds
// Refresh — recalculate bounds after external layout changes
sm.refresh();
// Pause / resume tracking without destroying
sm.disable(); // disconnects all observers, freezes progress
sm.enable(); // reco

nnects observers, recalculates from current state
sm.disabled; // read-only, true when disabled or destroyed
// Lifecycle
sm.destroy();
// Static
ScrollMagic.defaultOptions({ vertical: false }); // 새 인스턴스의 기본값을 가져오거나 설정합니다.
ScrollMagic.refreshAll(); // 모든 활성 인스턴스를 새로고침합니다.
ScrollMagic.destroyAll(); // 모든 활성 인스턴스를 제거합니다.
```
## `refresh()`를 사용해야 하는 시기
ScrollMagic은 (`ResizeObserver`를 통해) 요소 크기 변경과 스크롤 위치 변경을 자동으로 추적합니다. 하지만 일부 레이아웃 변경은 이러한 관찰자가 감지할 수 없습니다. 즉, 요소의 \*\*크기\*\*를 변경하거나 스크롤 이벤트를 발생시키지 않고 \*\*위치\*\*만 변경하는 경우입니다.
다음의 경우에 `refresh()`(또는 `ScrollMagic.refreshAll()`)를 호출하세요.
- \*\*CSS 위치/여백/패딩 변경 시\*\* — `element.style.marginTop = '20px'`
- \*\*레이아웃에 영향을 주는 CSS 클래스 토글 시\*\* — `element.classList.add('expanded')`
- \*\*DOM 구조 변경 시\*\* — 요소 위쪽에 형제 요소가 추가되거나 제거되어 위치가 이동하는 경우
- \*\*명시적인 크기 지정 없이 이미지가 로드될 때\*\* — 추적 중인 요소 위의 `![]()`가 로드되면서 확장되어 요소를 아래로 밀어내는 경우
- \*\*폰트 로딩 시\*\* — `document.fonts.ready.then(() => ScrollMagic.refreshAll())`
- \*\*SPA의 라우트 변경 시\*\* — 콘텐츠 교체로 인해 스크롤 높이가 변경되는 경우
- \*\*동적 콘텐츠 로딩 시\*\* — CMS가 주입한 콘텐츠, 서드파티 위젯
```js
// 위치에 영향을 주는 스타일을 변경한 후
element.style.marginTop = '100px';
sm.refresh();
// 폰트 로딩이 완료된 후 (텍스트 리플로우에 영향)
document.fonts.ready.then(() => ScrollMagic.refreshAll());
// 레이아웃을 변경하는 프레임워크 리렌더링 후
onRouteChange(() => ScrollMagic.refreshAll());
```
`refresh()`는 \*\*다음 스크롤 이벤트가 발생하기 전\*\*에 경계(bounds)를 업데이트하고 싶을 때만 필요합니다. 사용자가 계속 스크롤하는 경우, 어차피 모든 스크롤 프레임마다 요소의 위치가 다시 읽혀집니다. `refresh()`가 중요한 경우는 추적이 활성화된 상태에서 스크롤 위치는 그대로 유지된 채 레이아웃이 변경될 때입니다(예: 스크롤 없이 클래스를 토글하거나 콘텐츠를 주입하는 경우).
`refresh()`는 비동기로 작동합니다. 다음 애니메이션 프레임에 재계산을 예약하고 즉시 반환됩니다. 동일한 프레임 내에서의 여러 `refresh()` 호출은 자동으로 일괄 처리(batch)됩니다.
## 플러그인
ScrollMagic은 인스턴스 동작을 확장하기 위한 플러그인 시스템을 제공합니다.
```ts
sm.addPlugin(myPlugin);
sm.removePlugin(myPlugin);
```
전체 플러그인 작성 가이드는 [PLUGINS.md](PLUGINS.md)를 참조하세요.
## 브라우저 지원
Chrome 73+, Firefox 69+, Safari 13.1+, Edge 79+ (`ResizeObserver` 지원 기준).
## 라이선스
MIT — [Jan Paepke](https://janpaepke.de)