Problem: With standard progress bars, one scroll event can jump multiple array items.
Solution: Use totalBlocks with scrollsPerBlock for precise control.

`tsx
import { useRef } from "react"
import { useScrollProgress } from "@meadown/scroll-progress-trigger"

function ImageGallery() {
const triggerRef = useRef(null)
const images = [
"photo1.jpg",
"photo2.jpg",
"photo3.jpg",
"photo4.jpg",
"photo5.jpg"
]

const { currentIndex, blockProgress } = useScrollProgress({
triggerRef,
totalBlocks: images.length,
scrollsPerBlock: 3, // Requires 3 scroll events to move to next image
onIndexChange: (current, previous) => {
console.log(Changed from image ${previous} to ${current})
}
})

return (


| Option | Type | Default | Description |
| -------------------- | --------------------------------------------- | ----------- | ------------------------------------------------------ |
| onComplete | () => void | undefined | Callback fired when progress reaches 100% |
| scrollDuration | number | 3000 | Duration in milliseconds for full progress |
| triggerRef | React.MutableRefObject | undefined | Element that triggers progress on hover/touch |
| scrollDirection | 'natural' \| 'inverted' \| 'system' | 'system' | Scroll direction behavior (auto-detects when 'system') |
| isAutoHoldProgress | boolean | true | Whether progress holds when not scrolling vs auto-decreases |
| totalBlocks | number | undefined | Divide progress into discrete blocks/indices |
| scrollsPerBlock | number | 1 | Number of scroll events required to advance one block |
| snapToBlocks | boolean | false | Snap progress to exact block boundaries |
| onIndexChange | (current: number, previous: number) => void | undefined | Callback fired when block index changes |
| onBlockProgress | (index: number, progress: number) => void | undefined | Callback fired on scroll with current block progress |

$3

| Value | Type | Description |
| --------------- | ------------ | --------------------------------------------- |
| progress | number | Current progress value (0-100) |
| resetProgress | () => void | Function to reset progress to 0 |
| isActive | boolean | Whether scroll progress is currently active |
| currentIndex | number | Current block index (when totalBlocks is set) |
| previousIndex | number | Previous block index (when totalBlocks is set)|
| blockProgress | number | Progress within current block 0-100 |

Scroll Direction Behavior

The library automatically adapts to your natural scroll preferences:

- 'system' (default): Automatically detects your scroll direction preference within the first 5 scroll interactions
- 'natural': Scroll down = increase progress (like iOS/macOS natural scrolling)
- 'inverted': Scroll down = decrease progress (traditional scrolling)

$3

When using scrollDirection: 'system', the library:

1. Collects your first 5 scroll interactions
2. Analyzes your expected vs actual behavior patterns
3. Automatically adapts to match your natural scrolling preference
4. Falls back to device heuristics if needed

`tsx
const { progress } = useScrollProgress({
scrollDirection: "system" // Auto-detects your preference
// scrollDirection: 'natural', // Force natural scrolling
// scrollDirection: 'inverted', // Force traditional scrolling
})
`

Progress Hold Behavior

Control what happens when you stop scrolling:

$3

`tsx
const { progress } = useScrollProgress({
isAutoHoldProgress: true, // Progress stays at 50% if you stop scrolling at 50%
})
`

$3

`tsx
const { progress } = useScrollProgress({
isAutoHoldProgress: false, // Progress drops from 50% → 0 when you stop scrolling
})
`

$3

`tsx
import React, { useRef } from "react"
import { useScrollProgress } from "@meadown/scroll-progress-trigger"

function ImageGallery() {
const triggerRef = useRef(null)
const images = ['img1.jpg', 'img2.jpg', 'img3.jpg', 'img4.jpg', 'img5.jpg']

const { currentIndex } = useScrollProgress({
totalBlocks: images.length,
scrollsPerBlock: 3, // Requires 3 scrolls to move to next image
triggerRef,
onIndexChange: (current, previous) => {
console.log(Moved from image ${previous} to ${current})
}
})

return (


Image ${currentIndex + 1}} />

Image {currentIndex + 1} of {images.length}