@dong-gri/motionkit

---

MotionKit은 34개의 인터랙션 모듈(모션·미디어·스크롤·로더·텍스트)을 data-mk-* 속성 하나로 붙이거나 JavaScript API로 세밀하게 제어할 수 있는 라이브러리입니다. 코어는 외부 의존성이 없으며, 미지원 브라우저나 저사양 기기에서는 효과만 비활성화되고 콘텐츠는 그대로 유지됩니다.

AI 코딩 도구(Cursor, Claude 등)로 작업한다면 AI 프롬프트 가이드를 참고하세요. 모션·인터랙션을 MotionKit 모듈로 우선 적용하도록 지시하는, 그대로 붙여넣는 프롬프트가 들어 있습니다.

설치

npm

npm install @dong-gri/motionkit

import MotionKit from '@dong-gri/motionkit';
import '@dong-gri/motionkit/style.css';

MotionKit.autoInit();

CDN (설치 없이 script 태그)

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@dong-gri/motionkit/dist/motionkit.min.css">
<script src="https://cdn.jsdelivr.net/npm/@dong-gri/motionkit/dist/motionkit.umd.min.js"></script>
<script>
  MotionKit.autoInit();
</script>

CDN (ESM)

import MotionKit from 'https://cdn.jsdelivr.net/npm/@dong-gri/motionkit/+esm';

빠른 시작

HTML 속성만으로 동작합니다.

<h2 data-mk-text-reveal="stream">문장이 흐르듯 나타납니다</h2>
<strong data-mk-counter="pop" data-mk-to="98760" data-mk-format=",">98,760</strong>
<img data-mk-lazy="skeleton" data-src="./cover.webp" alt="Cover">
<section data-mk-reveal="fade-up">스크롤 진입 시 나타납니다</section>

동일한 기능을 JavaScript API로도 쓸 수 있습니다.

MotionKit.counter('#total', { preset: 'pop', to: 98760, format: ',' });
MotionKit.reveal('.card', { preset: 'fade-up', stagger: 0.06 });
const lightbox = MotionKit.lightbox('.gallery img', { group: 'work', minimap: true });

선택적 의존성

코어는 단독으로 동작합니다. 아래 라이브러리가 페이지에 있으면 자동으로 감지해 스크롤 스크럽(GSAP + ScrollTrigger)과 스무스 스크롤(Lenis)에 활용하고, 없으면 표준 API로 폴백합니다.

<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/ScrollTrigger.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/lenis@1/dist/lenis.min.js"></script>

스무스 스크롤은 기본 비활성화이며, 필요할 때만 켤 수 있습니다.

MotionKit.enableSmooth({ lerp: 0.08 });
MotionKit.disableSmooth();

모듈

모듈	활성화 속성	용도
ambientMedia	data-mk-ambient-media	미디어 주변광(Ambient Glow)
blurText	data-mk-blur-text	글자별 블러 리빌
brushReveal	data-mk-brush-reveal	포인터 브러시 마스크 리빌
cardGlow	data-mk-card-glow	포인터 스포트라이트·표면 반사·발광 외곽선
counter	data-mk-counter	숫자 카운트·플립·시계·카운트다운
cssScroll	data-mk-css-scroll	CSS 변수·애니메이션 타임라인 스크롤 연동
cursor	data-mk-cursor	커스텀 커서 11종
fullpage	data-mk-fullpage	풀페이지 섹션 페이징(세로·가로·혼합축)
glitch	data-mk-glitch	RGB 슬라이스·글리치 리빌
lazy	data-mk-lazy	이미지 로딩 연출(스켈레톤·픽셀·프린트·디졸브)
lightbox	data-mk-lightbox	전체화면 뷰어·그룹·확대·미니맵
loader	data-mk-loader	실제 진행률 연동 로더
magnetic	data-mk-magnetic	포인터 자석 반응
marquee	data-mk-marquee	무한 흐름 텍스트
mouseParallax	data-mk-mouse-parallax	포인터·자이로 패럴럭스
overflowText	data-mk-overflow-text	넘치는 텍스트 처리 8종
pageReveal	data-mk-page-reveal	페이지 진입 오버레이
pageTransition	data-mk-page-transition	동일 출처 페이지 전환
parallax	data-mk-parallax	스크롤 패럴럭스
progress	data-mk-progress	읽기 진행률 바·링
reveal	data-mk-reveal	스크롤 진입 리빌
ripple	data-mk-ripple	클릭 리플
scrollSequence	data-mk-scroll-sequence	이미지 시퀀스 스크럽
scrollVelocity	data-mk-scroll-velocity	스크롤 속도·방향 반응
shuffle	data-mk-shuffle	문자 셔플 디코드
slider	data-mk-slider	슬라이드·커버플로우
stickyStack	data-mk-sticky-stack	스티키 스택(세로·가로·플로팅)
textFill	data-mk-text-fill	스크롤 텍스트 채움
textReveal	data-mk-text-reveal	텍스트 리빌(한글 조합 포함)
textSplit	data-mk-text-split	글자·단어 분할 모션
textTransition	data-mk-text-transition	텍스트 교체 전환
tilt	data-mk-tilt	3D 틸트·글레어
typewriter	data-mk-typewriter	타이핑 효과
vibrate	data-mk-vibrate	햅틱 진동 피드백

각 모듈의 variant와 옵션 전체 목록은 모듈 레퍼런스와 motionkit.features.json을 참고하세요.

프레임워크 어댑터

import { Motion } from '@dong-gri/motionkit/react';
<Motion as="h2" type="textReveal" options={{ mode: 'hangul' }}>안녕하세요</Motion>

import MotionKitVue from '@dong-gri/motionkit/vue';
app.use(MotionKitVue);

import installMotionKit from '@dong-gri/motionkit/jquery';
installMotionKit(window.jQuery);
$('.card').motionKit('reveal', { preset: 'fade-up' });

브라우저 지원

Chrome, Edge, Firefox, Safari(데스크톱·모바일)의 최신 버전을 지원합니다. prefers-reduced-motion을 켜면 모든 모듈이 애니메이션 없이 최종 상태로 렌더링되며, 미지원 환경에서는 효과가 정적 콘텐츠로 자동 축소됩니다.

빌드

npm install
npm run build   # dist/ 생성
npm run verify  # lint · build · 테스트 · 계약 검증

라이선스

MIT dongri