@@ -140,14 +152,16 @@ React Scrollama components do not render into the DOM. They are meant to set up
These are the props you can set on the `Scrollama` component itself:
-| Prop | Type | Default | Description |
-| -------------- | ---------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
-| offset | `number` (from 0 to 1) or pixel value (e.g. "300px") | 0.3 | How far from the top of the viewport to trigger a step (as a proportion of view height) |
-| threshold | `number` (greater than 1) | 4 | Granularity of the progress interval in pixels (smaller = more granular) |
-| onStepEnter | `function` | | Callback that fires when the top or bottom edge of a step enters the offset threshold. |
-| onStepExit | `function` | | Callback that fires when the top or bottom edge of a step exits the offset threshold. |
-| onStepProgress | `function` | | Callback that fires the progress a step has made through the threshold. |
-| debug | `boolean` | false | Whether to show visual debugging tools. |
+| Prop | Type | Default | Description |
+| -------------- | ---------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- |
+| offset | `number` (from 0 to 1) or pixel value (e.g. "300px") | 0.3 | How far from the top of the viewport to trigger a step (as a proportion of view height) |
+| threshold | `number` (greater than 1) | 4 | Granularity of the progress interval in pixels (smaller = more granular) |
+| onStepEnter | `function` | | Callback that fires when the top or bottom edge of a step enters the offset threshold. |
+| onStepExit | `function` | | Callback that fires when the top or bottom edge of a step exits the offset threshold. |
+| onStepProgress | `function` | | Callback that fires the progress a step has made through the threshold. |
+| debug | `boolean` | false | Whether to show visual debugging tools. |
+| rootRef | `React.RefObject
` | undefined | The root element of the IntersectionObserver. |
+| direction | `vertical \| horizontal` | horizontal | The direction of the trigger line. |
The `onStepEnter` and `onStepExit` callbacks receive one argument, an object, with the following properties:
@@ -180,9 +194,9 @@ A `Step` element can contain one child, which must be a DOM element. To use a Re
These are the props you can set on the `Step` component:
-| Prop | Type | Default | Description |
-| ---- | ---- | ------- | ---------------------------------------------------------------- |
-| data | any | | Data to be given to `` callbacks when step triggered. |
+| Prop | Type | Default | Description |
+| ---- | ------- | ------- | ---------------------------------------------------------------- |
+| data | unknown | | Data to be given to `` callbacks when step triggered. |
You will also probably want to set a `key` prop on each `Step` if you're transforming an array of data into a list of `Step` elements (see [Lists and Keys](https://reactjs.org/docs/lists-and-keys.html)).
diff --git a/example/public/index.html b/example/index.html
similarity index 80%
rename from example/public/index.html
rename to example/index.html
index b7188d8..02c6472 100644
--- a/example/public/index.html
+++ b/example/index.html
@@ -2,35 +2,26 @@
React Scrollama: Scrollytelling for React
@@ -59,5 +50,6 @@
You need to enable JavaScript to run this app.
+
diff --git a/example/package.json b/example/package.json
index 3cee291..a7e18fa 100644
--- a/example/package.json
+++ b/example/package.json
@@ -4,30 +4,24 @@
"version": "0.0.0",
"private": true,
"license": "MIT",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "tsc -b && vite build",
+ "lint": "eslint .",
+ "preview": "vite preview"
+ },
"dependencies": {
- "prop-types": "^15.8.1",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-jss": "^10.10.0",
- "react-scripts": "^5.0.1",
"react-scrollama": "file:../"
},
- "scripts": {
- "start": "react-scripts start",
- "build": "react-scripts build",
- "test": "react-scripts test --env=jsdom",
- "eject": "react-scripts eject"
- },
- "browserslist": {
- "production": [
- ">0.2%",
- "not dead",
- "not op_mini all"
- ],
- "development": [
- "last 1 chrome version",
- "last 1 firefox version",
- "last 1 safari version"
- ]
+ "devDependencies": {
+ "@types/react": "^19.0.10",
+ "@types/react-dom": "^19.0.4",
+ "@vitejs/plugin-react": "^4.3.4",
+ "typescript": "^5.8.2",
+ "vite": "^6.2.0"
}
}
diff --git a/example/src/Demo.jsx b/example/src/Demo.jsx
deleted file mode 100644
index 3392664..0000000
--- a/example/src/Demo.jsx
+++ /dev/null
@@ -1,314 +0,0 @@
-import React, { PureComponent } from 'react';
-import injectSheet from 'react-jss';
-import { Scrollama, Step } from 'react-scrollama';
-
-const styles = {
- navbar: {
- position: 'fixed',
- display: 'flex',
- top: 0,
- right: 0,
- zIndex: 1,
- '& a': {
- display: 'block',
- fontSize: '20px',
- padding: '20px',
- },
- },
- pageTitle: {
- textAlign: 'center',
- fontSize: 22,
- margin: '90px 0 10px',
- visibility: 'hidden',
- },
- description: {
- maxWidth: 600,
- margin: '10px auto 30px',
- fontSize: 22,
- lineHeight: '28px',
- '& a': {
- color: 'black',
- },
- },
- pageSubtitle: {
- textAlign: 'center',
- fontSize: 22,
- color: '#888',
- },
- graphicContainer: {
- padding: '40vh 2vw 20vh',
- display: 'flex',
- justifyContent: 'space-between',
- },
- graphic: {
- flexBasis: '60%',
- position: 'sticky',
- width: '100%',
- height: '60vh',
- top: '20vh',
- backgroundColor: '#aaa',
- display: 'flex',
- alignItems: 'center',
- justifyContent: 'center',
- '& p': {
- fontSize: '5rem',
- fontWeight: 700,
- textAlign: 'center',
- color: '#fff',
- },
- },
- scroller: {
- flexBasis: '35%',
- },
- step: {
- margin: '0 auto 3rem auto',
- padding: '180px 0',
- border: '1px solid #333',
- '& p': {
- textAlign: 'center',
- padding: '1rem',
- fontSize: '1.8rem',
- margin: 0,
- },
- '&:last-child': {
- marginBottom: 0,
- },
- },
- button: {
- backgroundColor: '#3773ac',
- color: 'white',
- borderRadius: '4px',
- cursor: 'pointer',
- padding: '6px',
- textAlign: 'center',
- display: 'block',
- maxWidth: 220,
- margin: '10px auto 30px',
- fontSize: 19,
- lineHeight: '28px',
- textDecoration: 'none',
- },
- subhed: {
- maxWidth: 600,
- margin: '10px auto 15px',
- fontSize: 22,
- lineHeight: '28px',
- '& a': {
- color: 'black',
- },
- textAlign: 'center',
- },
- whoUsing: {
- maxWidth: 960,
- margin: '30px auto 100px',
- fontSize: 19,
- lineHeight: '26px',
- gridAutoRows: 'minmax(100px, auto)',
- '& a': {
- color: 'black',
- },
- '& img': {
- width: '100%',
- },
- display: 'grid',
- gridTemplateColumns: '2fr 5fr',
- '& > div': {
- padding: '16px 0',
- borderTop: '1px solid #ccc',
- '&:nth-child(odd)': {
- paddingRight: '13px',
- borderRight: '1px solid #ccc',
- },
- '&:nth-child(even)': {
- paddingLeft: '13px',
- },
- },
- },
-};
-
-class Demo extends PureComponent {
- state = {
- data: 0,
- steps: [10, 20, 30],
- progress: 0,
- };
-
- onStepEnter = e => {
- const { data, entry, direction } = e;
- this.setState({ data });
- };
-
- onStepExit = ({ direction, data }) => {
- if (direction === 'up' && data === this.state.steps[0]) {
- this.setState({ data: 0 });
- }
- };
-
- onStepProgress = ({ progress }) => {
- this.setState({ progress });
- };
-
- render() {
- const { data, steps, progress } = this.state;
- const { classes } = this.props;
-
- return (
-
-
-
-
- React Scrollama
- {' '}
- Demo
-
-
- React Scrollama is a lightweight and simple interface for
- scrollytelling in React that uses IntersectionObserver in favor of
- scroll events. The library has been used by the{' '}
- World Bank's {' '}
- Atlas of Sustainable Development Goals and Politico.
-
-
-
- Learn and get started
-
-
-
Scroll ↓
-
-
-
- {steps.map(value => {
- const isVisible = value === data;
- const background = isVisible
- ? `rgba(44,127,184, ${progress})`
- : 'white';
- const visibility = isVisible ? 'visible' : 'hidden';
- return (
-
-
-
step value: {value}
-
- {Math.round(progress * 1000) / 10 + '%'}
-
-
- );
- })}
-
-
-
-
-
- Who's using React Scrollama?
-
-
-
- Learn and get started
-
-
= ({ data }) => {
+ setData(data);
+ };
+
+ const onStepExit: ScrollamaCallback = ({ direction, data }) => {
+ if (direction === 'up' && data === steps[0]) {
+ setData(0);
+ }
+ };
+
+ const onStepProgress: ScrollamaProgressCallback = ({ progress }) => {
+ setProgress(progress);
+ };
+
+ return (
+
+
+
+ React Scrollama
+ Demo
+
+
+ React Scrollama is a lightweight and simple interface for scrollytelling in React
+ that uses IntersectionObserver in favor of scroll events. The library has been used by the
+ World Bank's
+ Atlas of Sustainable Development Goals and Politico.
+
+
+
+ Learn and get started
+
+
+
Scroll ↓
+
+
+
+ onStepEnter={onStepEnter}
+ onStepExit={onStepExit}
+ onStepProgress={onStepProgress}
+ offset="400px"
+ debug>
+ {steps.map((value) => {
+ const isVisible = value === data;
+ const background = isVisible ? `rgba(44,127,184, ${progress})` : 'white';
+ const visibility = isVisible ? 'visible' : 'hidden';
+ return (
+
+
+
step value: {value}
+
{`${Math.round(progress * 1000) / 10}%`}
+
+ );
+ })}
+
+
+
+
+
+ Who's using React Scrollama?
+
+
+
+ Learn and get started
+
+
+
+);
diff --git a/example/src/style.ts b/example/src/style.ts
new file mode 100644
index 0000000..577ea35
--- /dev/null
+++ b/example/src/style.ts
@@ -0,0 +1,125 @@
+import { createUseStyles } from 'react-jss';
+
+export const useStyles = createUseStyles({
+ navbar: {
+ position: 'fixed',
+ display: 'flex',
+ top: 0,
+ right: 0,
+ zIndex: 1,
+ '& a': {
+ display: 'block',
+ fontSize: '20px',
+ padding: '20px',
+ },
+ },
+ pageTitle: {
+ textAlign: 'center',
+ fontSize: 22,
+ margin: '90px 0 10px',
+ visibility: 'hidden',
+ },
+ description: {
+ maxWidth: 600,
+ margin: '10px auto 30px',
+ fontSize: 22,
+ lineHeight: '28px',
+ '& a': {
+ color: 'black',
+ },
+ },
+ pageSubtitle: {
+ textAlign: 'center',
+ fontSize: 22,
+ color: '#888',
+ },
+ graphicContainer: {
+ padding: '40vh 2vw 20vh',
+ display: 'flex',
+ justifyContent: 'space-between',
+ },
+ graphic: {
+ flexBasis: '60%',
+ position: 'sticky',
+ width: '100%',
+ height: '60vh',
+ top: '20vh',
+ backgroundColor: '#aaa',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ '& p': {
+ fontSize: '5rem',
+ fontWeight: 700,
+ textAlign: 'center',
+ color: '#fff',
+ },
+ },
+ scroller: {
+ flexBasis: '35%',
+ },
+ step: {
+ margin: '0 auto 3rem auto',
+ padding: '180px 0',
+ border: '1px solid #333',
+ '& p': {
+ textAlign: 'center',
+ padding: '1rem',
+ fontSize: '1.8rem',
+ margin: 0,
+ },
+ '&:last-child': {
+ marginBottom: 0,
+ },
+ },
+ button: {
+ backgroundColor: '#3773ac',
+ color: 'white',
+ borderRadius: '4px',
+ cursor: 'pointer',
+ padding: '6px',
+ textAlign: 'center',
+ display: 'block',
+ maxWidth: 220,
+ margin: '10px auto 30px',
+ fontSize: 19,
+ lineHeight: '28px',
+ textDecoration: 'none',
+ },
+ subhed: {
+ maxWidth: 600,
+ margin: '10px auto 15px',
+ fontSize: 22,
+ lineHeight: '28px',
+ '& a': {
+ color: 'black',
+ },
+ textAlign: 'center',
+ },
+ whoUsing: {
+ maxWidth: 960,
+ margin: '30px auto 100px',
+ fontSize: 19,
+ lineHeight: '26px',
+ gridAutoRows: 'minmax(100px, auto)',
+ '& a': {
+ color: 'black',
+ },
+ '& img': {
+ width: '100%',
+ },
+ display: 'grid',
+ gridTemplateColumns: '2fr 5fr',
+ '& > div': {
+ padding: '16px 0',
+ borderTop: '1px solid #ccc',
+ '&:nth-child(odd)': {
+ paddingRight: '13px',
+ borderRight: '1px solid #ccc',
+ },
+ '&:nth-child(even)': {
+ paddingLeft: '13px',
+ },
+ },
+ },
+});
diff --git a/example/tsconfig.json b/example/tsconfig.json
new file mode 100644
index 0000000..7cde9e1
--- /dev/null
+++ b/example/tsconfig.json
@@ -0,0 +1,25 @@
+{
+ "compilerOptions": {
+ "module": "ESNext",
+ "target": "ESNext",
+ "useDefineForClassFields": true,
+ "lib": ["ES2020", "DOM", "DOM.Iterable"],
+ "skipLibCheck": true,
+
+ /* Bundler mode */
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "isolatedModules": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+ "jsx": "react-jsx",
+
+ /* Linting */
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "noFallthroughCasesInSwitch": true
+ },
+ "include": ["src"],
+ "exclude": ["dist"]
+}
diff --git a/example/vite.config.ts b/example/vite.config.ts
new file mode 100644
index 0000000..6b8b347
--- /dev/null
+++ b/example/vite.config.ts
@@ -0,0 +1,12 @@
+/// (https://jasonkao.me)",
"license": "MIT",
"homepage": "https://jsonkao.github.io/react-scrollama/",
- "main": "dist/index.js",
- "module": "dist/index.es.js",
+ "main": "./dist/index.cjs",
+ "module": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "import": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ },
+ "require": {
+ "types": "./dist/index.d.cts",
+ "default": "./dist/index.cjs"
+ }
+ }
+ },
+ "files": [
+ "dist"
+ ],
+ "sideEffects": false,
"workspaces": [
".",
"example"
@@ -26,55 +44,63 @@
"url": "https://github.com/jsonkao/react-scrollama"
},
"engines": {
- "node": ">=8",
- "npm": ">=5"
+ "node": ">=18.0.0",
+ "npm": ">=10.7.0"
},
"scripts": {
- "build": "rollup -c",
- "start": "rollup -c -w",
+ "prepare": "simple-git-hooks",
+ "start": "tsup --watch",
+ "build": "tsup",
+ "release": "bumpp && npm publish",
+ "prepublishOnly": "npm run build && npm run test",
+ "predeploy": "cd example && npm install && npm run build",
+ "deploy": "gh-pages -d example/build",
+ "coverage": "vitest run --coverage",
+ "test": "vitest",
"check": "npm run check:format && npm run check:lint",
"check:lint": "eslint . --report-unused-disable-directives",
"check:format": "prettier --write .",
- "prepublishOnly": "npm run build",
- "predeploy": "cd example && npm install && npm run build",
- "deploy": "gh-pages -d example/build",
- "test": "echo \"Error: no test specified\""
+ "typecheck": "tsc --noEmit"
},
"peerDependencies": {
- "react": "^16.8.0 || ^17.0.2 || ^18.2.0 || ^19.0.0",
- "react-dom": "^16.8.0 || ^17.0.2 || ^18.2.0 || ^19.0.0"
+ "react": ">= 16.8.0",
+ "react-dom": ">= 16.8.0"
},
"devDependencies": {
- "@babel/core": "^7.26.9",
- "@babel/eslint-parser": "^7.26.8",
- "@babel/preset-env": "^7.18.6",
- "@babel/preset-react": "^7.18.6",
"@eslint/compat": "^1.2.7",
- "@eslint/eslintrc": "^3.2.0",
- "@eslint/js": "^9.20.0",
- "@rollup/plugin-babel": "^6.0.4",
- "@rollup/plugin-commonjs": "^28.0.2",
- "@rollup/plugin-node-resolve": "^16.0.0",
- "@babel/plugin-transform-class-properties": "^7.25.9",
- "eslint": "^9.20.1",
- "eslint-plugin-import": "^2.26.0",
+ "@eslint/eslintrc": "^3.3.0",
+ "@eslint/js": "^9.21.0",
+ "@testing-library/jest-dom": "^6.6.3",
+ "@testing-library/react": "^16.2.0",
+ "@types/react": "^19.0.10",
+ "@vitejs/plugin-react": "^4.3.4",
+ "bumpp": "^10.0.3",
+ "eslint": "^9.21.0",
+ "eslint-plugin-import": "^2.31.0",
"eslint-plugin-jsx-a11y": "^6.10.2",
"eslint-plugin-react": "^7.37.4",
"gh-pages": "^6.3.0",
"globals": "^16.0.0",
- "prettier": "^3.5.1",
- "rollup": "^4.34.8",
- "rollup-plugin-peer-deps-external": "^2.2.4"
- },
- "files": [
- "dist"
- ],
- "prettier": {
- "trailingComma": "all",
- "singleQuote": true,
- "arrowParens": "avoid"
+ "happy-dom": "^17.1.8",
+ "lint-staged": "^15.4.3",
+ "prettier": "^3.5.2",
+ "react": "^19.0.0",
+ "simple-git-hooks": "^2.11.1",
+ "tsup": "^8.4.0",
+ "typescript": "^5.8.2",
+ "vite": "^6.2.0",
+ "vitest": "^3.0.7"
},
"dependencies": {
- "react-intersection-observer": "^9.3.5"
+ "react-intersection-observer": "^9.16.0"
+ },
+ "simple-git-hooks": {
+ "pre-commit": "npx lint-staged"
+ },
+ "lint-staged": {
+ "*": [
+ "eslint --fix",
+ "prettier --write"
+ ]
}
}
diff --git a/rollup.config.mjs b/rollup.config.mjs
deleted file mode 100644
index 3ca0aaa..0000000
--- a/rollup.config.mjs
+++ /dev/null
@@ -1,32 +0,0 @@
-import peerDepsExternal from 'rollup-plugin-peer-deps-external';
-import babel from '@rollup/plugin-babel';
-import resolve from '@rollup/plugin-node-resolve';
-import commonjs from '@rollup/plugin-commonjs';
-import pkg from './package.json' with { type: 'json' };
-
-export default {
- input: 'src/index.js',
- output: [
- {
- file: pkg.main,
- format: 'cjs',
- sourcemap: true,
- },
- {
- file: pkg.module,
- format: 'es',
- sourcemap: true,
- },
- ],
- plugins: [
- peerDepsExternal(),
- babel({
- babelrc: false,
- presets: [['@babel/preset-env', { modules: false }], '@babel/react'],
- plugins: ['@babel/plugin-transform-class-properties'],
- exclude: 'node_modules/**',
- }),
- resolve(),
- commonjs(),
- ],
-};
diff --git a/src/DebugOffset.jsx b/src/DebugOffset.jsx
deleted file mode 100644
index 49bb81b..0000000
--- a/src/DebugOffset.jsx
+++ /dev/null
@@ -1,37 +0,0 @@
-import React from 'react';
-import { isOffsetInPixels } from './utils';
-
-const markerStyles = {
- position: 'fixed',
- left: 0,
- width: '100%',
- height: 0,
- borderTop: '2px dashed black',
- zIndex: 9999,
-};
-const offsetTextStyles = {
- fontSize: '12px',
- fontFamily: 'monospace',
- margin: 0,
- padding: 6,
-};
-
-const useTop = offset => {
- const offsetInPixels = isOffsetInPixels(offset);
- if (offsetInPixels) {
- return offset;
- } else {
- return `${offset * 100}%`;
- }
-};
-
-const DebugOffset = ({ offset }) => {
- const top = useTop(offset);
- return (
-
- );
-};
-
-export default DebugOffset;
diff --git a/src/Scrollama.jsx b/src/Scrollama.jsx
deleted file mode 100644
index 0181e03..0000000
--- a/src/Scrollama.jsx
+++ /dev/null
@@ -1,78 +0,0 @@
-import React, { useMemo, useEffect, useState } from 'react';
-import DebugOffset from './DebugOffset.jsx';
-import { isOffsetInPixels } from './utils';
-
-const createThreshold = (theta, height) => {
- const count = Math.ceil(height / theta);
- const t = [];
- const ratio = 1 / count;
- for (let i = 0; i <= count; i += 1) {
- t.push(i * ratio);
- }
- return t;
-};
-
-const Scrollama = props => {
- const {
- debug,
- children,
- offset = 0.3,
- onStepEnter = () => {},
- onStepExit = () => {},
- onStepProgress = null,
- threshold = 4,
- } = props;
- const isOffsetDefinedInPixels = isOffsetInPixels(offset);
- const [lastScrollTop, setLastScrollTop] = useState(0);
- const [windowInnerHeight, setWindowInnerHeight] = useState(null);
-
- const handleSetLastScrollTop = scrollTop => {
- setLastScrollTop(scrollTop);
- };
-
- const handleWindowResize = e => {
- setWindowInnerHeight(window.innerHeight);
- };
-
- useEffect(() => {
- if (isOffsetDefinedInPixels) {
- window.addEventListener('resize', handleWindowResize);
- return () => {
- window.removeEventListener('resize', handleWindowResize);
- };
- }
- }, []);
-
- const isBrowser = typeof window !== 'undefined';
- const innerHeight = isBrowser ? windowInnerHeight || window.innerHeight : 0;
-
- const offsetValue = isOffsetDefinedInPixels
- ? +offset.replace('px', '') / innerHeight
- : offset;
-
- const progressThreshold = useMemo(
- () => createThreshold(threshold, innerHeight),
- [innerHeight],
- );
-
- return (
- <>
- {debug && = ({
+ offset,
+ direction,
+ stickySize,
+ isHasRoot,
+ containerSize,
+}) => {
+ const offsetValue = getOffsetValue(offset, containerSize);
+ const commonStyles = isHorizontal(direction)
+ ? {
+ ...markerStylesHorizontal,
+ top: offsetValue,
+ }
+ : {
+ ...markerStylesVertical,
+ left: offsetValue,
+ };
+
+ return isHasRoot ? (
+
+ ) : (
+
+ );
+};
diff --git a/src/index.js b/src/index.js
deleted file mode 100644
index 40a7299..0000000
--- a/src/index.js
+++ /dev/null
@@ -1,2 +0,0 @@
-export { default as Scrollama } from './Scrollama.jsx';
-export { default as Step } from './Step.jsx';
diff --git a/src/index.ts b/src/index.ts
new file mode 100644
index 0000000..1668abd
--- /dev/null
+++ b/src/index.ts
@@ -0,0 +1,6 @@
+export * from './debug-offset';
+export * from './types';
+export * from './utils';
+export * from './step';
+export * from './scrollama';
+export * from './provide';
diff --git a/src/provide.tsx b/src/provide.tsx
new file mode 100644
index 0000000..5885917
--- /dev/null
+++ b/src/provide.tsx
@@ -0,0 +1,8 @@
+import { createContext } from 'react';
+
+import type { ScrollamaProvideProps } from './types';
+
+/**
+ * @see https://react.dev/reference/react/createContext#createcontext
+ */
+export const ScrollamaProvide = createContext>({});
diff --git a/src/scrollama.tsx b/src/scrollama.tsx
new file mode 100644
index 0000000..9000505
--- /dev/null
+++ b/src/scrollama.tsx
@@ -0,0 +1,104 @@
+import { useEffect, useMemo, useState } from 'react';
+
+import { DebugOffset } from './debug-offset';
+import { ScrollamaProvide } from './provide';
+import { createThreshold, isHorizontal, isOffsetInPixels } from './utils';
+
+import type { ScrollamaProps } from './types';
+
+export const Scrollama = ({
+ direction = 'horizontal',
+ debug,
+ children,
+ offset = 0.3,
+ onStepEnter,
+ onStepExit,
+ onStepProgress,
+ threshold = 4,
+ rootRef,
+}: ScrollamaProps) => {
+ const isOffsetDefinedInPixels = isOffsetInPixels(offset);
+ const [lastScrollPosition, setLastScrollPosition] = useState(0);
+ const [containerSize, setContainerSize] = useState(1);
+ const [stickySize, setStickySize] = useState(0);
+
+ const viewportSize = useMemo(() => {
+ return isHorizontal(direction) ? window.innerHeight : window.innerWidth;
+ }, [direction]);
+
+ const handleSetLastScrollPosition = (scrollPosition: number) => {
+ setLastScrollPosition(scrollPosition);
+ };
+
+ const handleResize = () => {
+ if (rootRef?.current) {
+ setContainerSize(
+ isHorizontal(direction) ? rootRef.current.clientHeight : rootRef.current.clientWidth,
+ );
+ setStickySize(
+ !isHorizontal(direction) ? rootRef.current.clientHeight : rootRef.current.clientWidth,
+ );
+ } else {
+ setContainerSize(viewportSize);
+ }
+ };
+
+ useEffect(() => {
+ if (isOffsetDefinedInPixels) {
+ if (rootRef?.current) {
+ const resizeObserver = new ResizeObserver(() => {
+ handleResize();
+ });
+ resizeObserver.observe(rootRef.current);
+ return () => {
+ resizeObserver.disconnect();
+ };
+ }
+
+ handleResize();
+ window.addEventListener('resize', handleResize);
+ return () => {
+ window.removeEventListener('resize', handleResize);
+ };
+ }
+ }, []);
+
+ const offsetValue = isOffsetDefinedInPixels
+ ? +(offset as string).replace('px', '') / containerSize
+ : +offset;
+
+ const progressThreshold = useMemo(
+ () => createThreshold(threshold, containerSize),
+ [containerSize],
+ );
+
+ return (
+
+ {debug && (
+
+ );
+};
diff --git a/src/step.tsx b/src/step.tsx
new file mode 100644
index 0000000..ffde51e
--- /dev/null
+++ b/src/step.tsx
@@ -0,0 +1,125 @@
+import {
+ Children,
+ cloneElement,
+ useCallback,
+ useContext,
+ useEffect,
+ useLayoutEffect,
+ useMemo,
+ useRef,
+ useState,
+} from 'react';
+import { useInView } from 'react-intersection-observer';
+
+import { ScrollamaProvide } from './provide';
+import type { ScrollamaCallbackData, StepProps } from './types';
+import { getProgressRootMargin, getRootMargin, isBrowser, isHorizontal } from './utils';
+
+export const Step: React.FC = ({ children, data }) => {
+ const {
+ handleSetLastScrollPosition = () => {},
+ lastScrollPosition = 0,
+ onStepEnter = () => {},
+ onStepExit = () => {},
+ onStepProgress = null,
+ offset = 0.3,
+ progressThreshold,
+ containerSize = 0,
+ rootRef,
+ direction = 'horizontal',
+ } = useContext(ScrollamaProvide);
+
+ const [nodeSize, setNodeSize] = useState(0);
+ const rootMargin = getRootMargin({ offset, direction });
+ const { ref: inViewRef, entry } = useInView({
+ root: rootRef?.current,
+ rootMargin,
+ threshold: 0,
+ });
+
+ const getScrollPosition = () => {
+ if (!isBrowser) return 0;
+ if (rootRef?.current) {
+ return isHorizontal(direction) ? rootRef.current.scrollTop : rootRef.current.scrollLeft;
+ }
+ return isHorizontal(direction) ? window.scrollY : window.scrollX;
+ };
+
+ const getScrollDirection = () => {
+ if (isHorizontal(direction)) {
+ return lastScrollPosition > getScrollPosition() ? 'up' : 'down';
+ }
+ return lastScrollPosition > getScrollPosition() ? 'left' : 'right';
+ };
+
+ const ref = useRef(null);
+ const [isIntersecting, setIsIntersecting] = useState(false);
+
+ const progressRootMargin = useMemo(
+ () => getProgressRootMargin({ offset, nodeSize, containerSize, direction }),
+ [offset, nodeSize, containerSize, direction],
+ );
+
+ const { ref: scrollProgressRef, entry: scrollProgressEntry } = useInView({
+ root: rootRef?.current,
+ rootMargin: progressRootMargin,
+ threshold: progressThreshold,
+ });
+
+ const setRefs = useCallback(
+ (node: HTMLElement) => {
+ ref.current = node;
+ inViewRef(node);
+ scrollProgressRef(node);
+ },
+ [inViewRef, scrollProgressRef],
+ );
+
+ useEffect(() => {
+ if (isIntersecting && scrollProgressEntry) {
+ const progress = scrollProgressEntry.intersectionRatio;
+ if (onStepProgress) {
+ onStepProgress({
+ progress: progress,
+ data,
+ element: scrollProgressEntry.target,
+ entry: scrollProgressEntry,
+ direction: getScrollDirection(),
+ });
+ }
+ }
+ }, [scrollProgressEntry]);
+
+ useEffect(() => {
+ if (entry) {
+ const currentIntersectionState = entry.isIntersecting;
+ if (currentIntersectionState !== isIntersecting) {
+ setIsIntersecting(currentIntersectionState);
+ const eventData: ScrollamaCallbackData = {
+ element: entry.target,
+ data,
+ entry,
+ direction: getScrollDirection(),
+ };
+ if (currentIntersectionState) {
+ onStepEnter(eventData);
+ } else {
+ onStepExit(eventData);
+ }
+ handleSetLastScrollPosition(getScrollPosition());
+ }
+ }
+ }, [entry]);
+
+ useLayoutEffect(() => {
+ if (ref.current) {
+ setNodeSize(isHorizontal(direction) ? ref.current.offsetHeight : ref.current.offsetWidth);
+ }
+ }, [ref.current]);
+
+ const childElement = Children.only(children);
+ const extraProps = {
+ ref: setRefs,
+ };
+ return cloneElement(childElement, extraProps);
+};
diff --git a/src/types.ts b/src/types.ts
new file mode 100644
index 0000000..87129ee
--- /dev/null
+++ b/src/types.ts
@@ -0,0 +1,174 @@
+/**
+ * Represents the direction of scrolling.
+ */
+export type ScrollamaDirection = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * Represents the direction of the trigger line.
+ */
+export type TriggerLineDirection = 'vertical' | 'horizontal';
+
+/**
+ * Interface for the data passed to Scrollama callback functions.
+ * @template T - The type of custom data associated with each step.
+ */
+export interface ScrollamaCallbackData {
+ /** The DOM element of the step */
+ element: Element;
+ /** Custom data associated with the step */
+ data: T;
+ /** The direction of scrolling */
+ direction: ScrollamaDirection;
+ /** The IntersectionObserverEntry for the step */
+ entry: IntersectionObserverEntry;
+}
+
+/**
+ * Interface for the data passed to Scrollama progress callback functions.
+ * Extends ScrollamaCallbackData with progress information.
+ * @template T - The type of custom data associated with each step.
+ */
+export interface ScrollamaProgressCallbackData extends ScrollamaCallbackData {
+ /** The progress of the step through the threshold, from 0 to 1 */
+ progress: number;
+}
+
+/**
+ * Type for Scrollama callback functions.
+ * @template T - The type of custom data associated with each step.
+ */
+export type ScrollamaCallback = (data: ScrollamaCallbackData) => void;
+
+/**
+ * Type for Scrollama progress callback functions.
+ * @template T - The type of custom data associated with each step.
+ */
+export type ScrollamaProgressCallback = (
+ data: ScrollamaProgressCallbackData,
+) => void;
+
+/**
+ * Interface for the props of the Scrollama component.
+ * @template T - The type of data associated with each step.
+ */
+export interface ScrollamaProps {
+ /**
+ * The direction of the trigger line.
+ * @default "horizontal"
+ */
+ direction?: TriggerLineDirection;
+ /**
+ * Whether to show visual debugging tools.
+ * @default false
+ */
+ debug?: boolean;
+
+ /**
+ * The child elements to be wrapped by Scrollama.
+ */
+ children: React.ReactNode;
+
+ /**
+ * How far from the top of the viewport to trigger a step.
+ * Can be a number from 0 to 1 (as a proportion of view height) or a pixel value (e.g. "300px").
+ * @default 0.3
+ */
+ offset?: string | number;
+
+ /**
+ * Callback that fires when the top or bottom edge of a step enters the offset threshold.
+ */
+ onStepEnter?: ScrollamaCallback;
+
+ /**
+ * Callback that fires when the top or bottom edge of a step exits the offset threshold.
+ */
+ onStepExit?: ScrollamaCallback;
+
+ /**
+ * Callback that fires the progress a step has made through the threshold.
+ */
+ onStepProgress?: ScrollamaProgressCallback;
+
+ /**
+ * Granularity of the progress interval in pixels (smaller = more granular).
+ * @default 4
+ */
+ threshold?: number;
+
+ /**
+ * The root element of the IntersectionObserver.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#root
+ */
+ rootRef?: React.RefObject;
+}
+
+/**
+ * Interface for the props of a Step component in Scrollama.
+ * @template T - The type of data associated with the step.
+ */
+export interface StepProps {
+ /**
+ * The child element to be rendered within the Step.
+ * Must be a valid React element with class attributes.
+ */
+ children: React.ReactElement & React.ClassAttributes;
+
+ /**
+ * Optional data associated with this step.
+ */
+ data?: T;
+}
+
+export interface ScrollamaProvideProps {
+ /**
+ * The direction of the trigger line.
+ */
+ direction?: TriggerLineDirection;
+
+ /**
+ * The last known scroll position.
+ */
+ lastScrollPosition?: number;
+
+ /**
+ * The offset value for triggering the step.
+ */
+ offset?: number;
+
+ /**
+ * The threshold for progress calculations.
+ */
+ progressThreshold?: number | number[];
+
+ /**
+ * The size of the container.
+ */
+ containerSize?: number;
+
+ /**
+ * The root element of the IntersectionObserver.
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver#root
+ */
+ rootRef?: React.RefObject;
+
+ /**
+ * Callback fired when the step enters the viewport.
+ */
+ onStepEnter?: ScrollamaCallback;
+
+ /**
+ * Callback fired when the step exits the viewport.
+ */
+ onStepExit?: ScrollamaCallback;
+
+ /**
+ * Callback fired to report progress as the step moves through the viewport.
+ */
+ onStepProgress?: ScrollamaProgressCallback;
+
+ /**
+ * Function to update the last known scroll position.
+ */
+ handleSetLastScrollPosition?: (scrollPosition: number) => void;
+}
diff --git a/src/utils.js b/src/utils.js
deleted file mode 100644
index 5c251dc..0000000
--- a/src/utils.js
+++ /dev/null
@@ -1,2 +0,0 @@
-export const isOffsetInPixels = offset =>
- typeof offset === 'string' && offset.includes('px');
diff --git a/src/utils.ts b/src/utils.ts
new file mode 100644
index 0000000..190694c
--- /dev/null
+++ b/src/utils.ts
@@ -0,0 +1,115 @@
+import type { TriggerLineDirection } from './types';
+
+/**
+ * Checks if the given offset is in pixels.
+ *
+ * @param offset - The offset to check.
+ * @returns Returns true if the offset is a string and includes 'px', otherwise false.
+ */
+export function isOffsetInPixels(offset: unknown) {
+ return typeof offset === 'string' && offset.includes('px');
+}
+
+/**
+ * Creates an array of threshold values for intersection observer.
+ *
+ * @param theta - The step size for creating thresholds.
+ * @param height - The total height to be divided into thresholds.
+ * @returns An array of threshold values between 0 and 1.
+ */
+export const createThreshold = (theta: number, height: number) => {
+ const count = Math.ceil(height / theta);
+ const t: number[] = [];
+ const ratio = 1 / count;
+ for (let i = 0; i <= count; i += 1) {
+ t.push(i * ratio);
+ }
+ return t;
+};
+
+/**
+ * Checks if the current environment is a browser.
+ *
+ * @returns {boolean} Returns true if running in a browser environment, false otherwise.
+ */
+export const isBrowser = typeof window !== 'undefined' && window.document !== undefined;
+
+export const isHorizontal = (direction: TriggerLineDirection) => direction === 'horizontal';
+
+/**
+ * Calculates the root margin for the Intersection Observer based on the given offset.
+ *
+ * @param {Object} params - The parameters object.
+ * @param {number} params.offset - The offset value, typically between 0 and 1.
+ * @param {TriggerLineDirection} params.direction - The direction of the trigger line.
+ * @returns {string} The calculated root margin string in the format "top right bottom left".
+ */
+export const getRootMargin = ({
+ offset,
+ direction,
+}: {
+ offset: number;
+ direction: TriggerLineDirection;
+}) => {
+ const calculateMargin = (offset: number) => `${-offset * 100}%`;
+ const calculateOppositeMargin = (offset: number) => `${-(100 - offset * 100)}%`;
+
+ if (isHorizontal(direction)) {
+ return [
+ calculateMargin(offset), // Top
+ '0px', // Right
+ calculateOppositeMargin(offset), // Bottom
+ '0px', // Left
+ ].join(' ');
+ }
+
+ return [
+ '0px', // Top
+ calculateOppositeMargin(offset), // Right
+ '0px', // Bottom
+ calculateMargin(offset), // Left
+ ].join(' ');
+};
+
+interface GetProgressRootMarginParams {
+ offset: number;
+ nodeSize: number;
+ containerSize: number;
+ direction: TriggerLineDirection;
+}
+
+/**
+ * Calculates the root margin for progress tracking based on scroll direction and element dimensions.
+ *
+ * @param {Object} params - The parameters for calculating the root margin.
+ * @param {number} params.offset - The offset value, typically between 0 and 1.
+ * @param {number} params.nodeSize - The size of the node.
+ * @param {number} params.containerSize - The size of the container.
+ * @param {TriggerLineDirection} params.direction - The direction of the trigger line.
+ * @returns {string} The calculated root margin string in the format "top right bottom left".
+ */
+export const getProgressRootMargin = ({
+ offset,
+ nodeSize,
+ containerSize,
+ direction,
+}: GetProgressRootMarginParams) => {
+ if (!nodeSize) return '0px';
+ const offsetSizeRatio = nodeSize / containerSize;
+ if (!isHorizontal(direction)) {
+ return `0px ${offset * 100 - 100}% 0px ${(offsetSizeRatio - offset) * 100 + 1}%`;
+ }
+ /**
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API
+ * Add an extra 1% to prevent the "zero intersection rectangle" phenomenon:
+ *
+ * 1. Prevents the root intersection rectangle from overlapping with the scrolling element, which could prevent triggering.
+ * 2. Due to rounding of decimal points in calculations, the height of the root intersection rectangle might be smaller than the scrolling element's height, preventing triggering.
+ *
+ * Why adding 1% doesn't affect progress calculation:
+ *
+ * When the intersection ratio of the scrolling observer is 1, the other observer's isIntersecting is false.
+ * Therefore, we don't need to worry about the impact of adding this extra value.
+ */
+ return `${(offsetSizeRatio - offset) * 100 + 1}% 0px ${offset * 100 - 100}% 0px`;
+};
diff --git a/tests/debug-offset.test.tsx b/tests/debug-offset.test.tsx
new file mode 100644
index 0000000..6787128
--- /dev/null
+++ b/tests/debug-offset.test.tsx
@@ -0,0 +1,108 @@
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+import { useRef } from 'react';
+import { describe, expect, it } from 'vitest';
+import { DebugOffset } from '../src';
+
+describe('DebugOffset', () => {
+ it('renders correctly with pixel offset', () => {
+ render(
+ (null);
+
+ return (
+
+
+ );
+};
+
+describe('HookComponent', () => {
+ it('should render correctly with pixel offset', async () => {
+ const { getByTestId } = render((0);
+ return (
+
+
debug onStepEnter={({ data }) => setCurrentStep(data)}>
+ {[1, 2, 3].map((stepNumber) => (
+
+
+ Step {stepNumber}
+
+
+ ))}
+
+
+
+ ,
+ );
+ const wrapper = screen.getByTestId('wrapper');
+
+ // Should not be updated until intersection observer triggers
+ expect(wrapper).toHaveAttribute('data-step', '0');
+
+ const step1 = screen.getByTestId('step-1');
+ const step2 = screen.getByTestId('step-2');
+ const step3 = screen.getByTestId('step-3');
+
+ act(() => {
+ mockIsIntersecting(step1, true);
+ });
+ expect(wrapper).toHaveAttribute('data-step', '1');
+ act(() => {
+ mockIsIntersecting(step1, false);
+ });
+ expect(wrapper).toHaveAttribute('data-step', '1');
+
+ act(() => {
+ mockIsIntersecting(step2, true);
+ });
+ expect(wrapper).toHaveAttribute('data-step', '2');
+ act(() => {
+ mockIsIntersecting(step2, false);
+ });
+ expect(wrapper).toHaveAttribute('data-step', '2');
+
+ act(() => {
+ mockIsIntersecting(step3, true);
+ });
+ expect(wrapper).toHaveAttribute('data-step', '3');
+ act(() => {
+ mockIsIntersecting(step3, false);
+ });
+ expect(wrapper).toHaveAttribute('data-step', '3');
+
+ // use screen.debug() to see the DOM
+ // screen.debug();
+ });
+});
diff --git a/tests/utils.test.ts b/tests/utils.test.ts
new file mode 100644
index 0000000..2f2e78f
--- /dev/null
+++ b/tests/utils.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import {
+ createThreshold,
+ getProgressRootMargin,
+ getRootMargin,
+ isBrowser,
+ isOffsetInPixels,
+} from '../src';
+
+describe('isOffsetInPixels', () => {
+ it('should return true for pixel offset', () => {
+ expect(isOffsetInPixels('10px')).toBe(true);
+ });
+
+ it('should return true for decimal pixel offset', () => {
+ expect(isOffsetInPixels('10.5px')).toBe(true);
+ });
+
+ it('should return false for non-pixel offset', () => {
+ expect(isOffsetInPixels('10%')).toBe(false);
+ });
+
+ it('should return false for numeric offset', () => {
+ expect(isOffsetInPixels(10)).toBe(false);
+ });
+
+ it('should return false for decimal numeric offset', () => {
+ expect(isOffsetInPixels(10.5)).toBe(false);
+ });
+});
+
+describe('createThreshold', () => {
+ it('should create an array of thresholds', () => {
+ const result = createThreshold(100, 1000);
+ expect(Array.isArray(result)).toBe(true);
+ expect(result.length).toBe(11); // 1000/100 rounded up + 1
+ });
+
+ it('should return thresholds between 0 and 1', () => {
+ const result = createThreshold(50, 200);
+ expect(result[0]).toBe(0);
+ expect(result[result.length - 1]).toBe(1);
+ for (const threshold of result) {
+ expect(threshold).toBeGreaterThanOrEqual(0);
+ expect(threshold).toBeLessThanOrEqual(1);
+ }
+ });
+
+ it('should handle edge case with small theta', () => {
+ const result = createThreshold(1, 10);
+ expect(result.length).toBe(11);
+ expect(result[1]).toBeCloseTo(0.1, 5);
+ });
+
+ it('should handle edge case with theta larger than height', () => {
+ const result = createThreshold(100, 50);
+ expect(result.length).toBe(2);
+ expect(result).toEqual([0, 1]);
+ });
+});
+
+describe('isBrowser', () => {
+ it('should return true when window and document are defined', () => {
+ expect(isBrowser).toBe(true);
+ });
+});
+
+describe('getRootMargin', () => {
+ it('should return the correct root margin', () => {
+ expect(getRootMargin({ offset: 0, direction: 'horizontal' })).toBe('0% 0px -100% 0px');
+ expect(getRootMargin({ offset: 0.5, direction: 'horizontal' })).toBe('-50% 0px -50% 0px');
+ expect(getRootMargin({ offset: 1, direction: 'horizontal' })).toBe('-100% 0px 0% 0px');
+ });
+});
+
+describe('getProgressRootMargin', () => {
+ it('should return "0px" when nodeSize is null', () => {
+ expect(
+ getProgressRootMargin({
+ direction: 'horizontal',
+ offset: 0,
+ nodeSize: 0,
+ containerSize: 0,
+ }),
+ ).toBe('0px');
+ });
+
+ it('should return correct margin for downward scrolling', () => {
+ const result = getProgressRootMargin({
+ direction: 'horizontal',
+ offset: 0.3,
+ nodeSize: 500,
+ containerSize: 1000,
+ });
+ expect(result).toBe('21% 0px -70% 0px');
+ });
+
+ it('should return correct margin for upward scrolling', () => {
+ const result = getProgressRootMargin({
+ direction: 'horizontal',
+ offset: 0.3,
+ nodeSize: 500,
+ containerSize: 1000,
+ });
+ expect(result).toBe('21% 0px -70% 0px');
+ });
+});
diff --git a/tests/vitest.setup.ts b/tests/vitest.setup.ts
new file mode 100644
index 0000000..1eeb244
--- /dev/null
+++ b/tests/vitest.setup.ts
@@ -0,0 +1,16 @@
+import '@testing-library/jest-dom/vitest';
+import { cleanup } from '@testing-library/react';
+import {
+ resetIntersectionMocking,
+ setupIntersectionMocking,
+} from 'react-intersection-observer/test-utils';
+import { afterEach, beforeEach, vi } from 'vitest';
+
+beforeEach(() => {
+ setupIntersectionMocking(vi.fn);
+});
+
+afterEach(() => {
+ resetIntersectionMocking();
+ cleanup();
+});
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 0000000..251a83f
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,20 @@
+{
+ "compilerOptions": {
+ "target": "ESNext",
+ "useDefineForClassFields": true,
+ "lib": ["DOM", "DOM.Iterable", "ESNext"],
+ "allowJs": false,
+ "skipLibCheck": true,
+ "esModuleInterop": false,
+ "allowSyntheticDefaultImports": true,
+ "strict": true,
+ "forceConsistentCasingInFileNames": true,
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "noEmit": true,
+ "jsx": "react-jsx"
+ },
+ "include": ["src"]
+}
diff --git a/tsup.config.ts b/tsup.config.ts
new file mode 100644
index 0000000..35377cf
--- /dev/null
+++ b/tsup.config.ts
@@ -0,0 +1,33 @@
+import type { Options } from 'tsup';
+import { defineConfig } from 'tsup';
+
+import pkg from './package.json';
+
+const banner = `/**
+ * Name: ${pkg.name}
+ * Version: ${pkg.version}
+ * Author: ${pkg.author}
+ * Homepage: ${pkg.homepage}
+ * License: ${pkg.license} © 2020-Present
+ */\n`;
+
+const baseOptions: Options = {
+ minify: false,
+ sourcemap: true,
+ dts: true,
+ clean: true,
+ target: 'es2020',
+ external: ['react'],
+ format: ['esm', 'cjs'],
+ banner: {
+ js: banner,
+ },
+};
+
+export default defineConfig([
+ {
+ ...baseOptions,
+ entryPoints: ['src/index.ts'],
+ outDir: 'dist',
+ },
+]);
diff --git a/vitest.config.ts b/vitest.config.ts
new file mode 100644
index 0000000..20c7e87
--- /dev/null
+++ b/vitest.config.ts
@@ -0,0 +1,10 @@
+/// 
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
+
+
+ 
- {' '}
- 
-
- 
-
- 
-
- 
-
- 
-
- 
-