@usefy/use-throttle

A high-performance React hook for throttling values with leading/trailing edge support

Installation •
Quick Start •
API Reference •
Examples •
License

---

Overview

@usefy/use-throttle limits value updates to at most once per specified interval, making it perfect for scroll events, resize handlers, mouse movements, and any high-frequency updates that need rate-limiting. Unlike debounce, throttle guarantees regular updates during continuous changes.

Part of the @usefy ecosystem — a collection of production-ready React hooks designed for modern applications.

$3

- Zero Dependencies — Pure React implementation (uses @usefy/use-debounce internally)
- TypeScript First — Full type safety with generics and exported interfaces
- Flexible Options — Leading edge and trailing edge support
- Guaranteed Updates — Regular updates during continuous changes (unlike debounce)
- SSR Compatible — Works seamlessly with Next.js, Remix, and other SSR frameworks
- Lightweight — Minimal bundle footprint (~200B minified + gzipped)
- Well Tested — Comprehensive test coverage with Vitest

$3

| Feature | Throttle | Debounce |
| -------------------- | -------------------------- | ----------------------------- |
| First update | Immediate (leading: true) | After delay |
| During rapid changes | Regular intervals | Waits for pause |
| Best for | Scroll, resize, mouse move | Search input, form validation |

---

Installation

``bash

`npm`


npm install @usefy/use-throttle
yarn

yarn add @usefy/use-throttle
pnpm

pnpm add @usefy/use-throttle


$3
This package requires React 18 or 19:

`json { "peerDependencies": { "react": "^18.0.0 || ^19.0.0" } }`

`$3`

This package uses @usefy/use-debounce internally with maxWait set to achieve throttle behavior.

---

`Quick Start`

`tsx import { useThrottle } from "@usefy/use-throttle";

function ScrollTracker() { const [scrollY, setScrollY] = useState(0); const throttledScrollY = useThrottle(scrollY, 100);

useEffect(() => { const handleScroll = () => setScrollY(window.scrollY); window.addEventListener("scroll", handleScroll); return () => window.removeEventListener("scroll", handleScroll); }, []);

return

Scroll position: {throttledScrollY}px

;
}


---
API Reference
$3
A hook that returns a throttled version of the provided value, limiting updates to at most once per interval.
#### Parameters

| Parameter | Type | Default | Description | | --------- | -------------------- | ------- | ------------------------------------- | |value | T| — | The value to throttle | |delay | number | 500| The throttle interval in milliseconds | |options | UseThrottleOptions | {} | Additional configuration options |

#### Options

| Option | Type | Default | Description | | ---------- | --------- | ------- | -------------------------------------------- | |leading | boolean | true| Update on the leading edge (first change) | |trailing | boolean | true | Update on the trailing edge (after interval) |

#### Returns

| Type | Description | | ---- | ------------------- | |T | The throttled value |

---

`Examples`

`$3`

`tsx import { useThrottle } from "@usefy/use-throttle";

function ScrollProgress() { const [scrollY, setScrollY] = useState(0); const throttledScrollY = useThrottle(scrollY, 100);

useEffect(() => { const handleScroll = () => setScrollY(window.scrollY); window.addEventListener("scroll", handleScroll, { passive: true }); return () => window.removeEventListener("scroll", handleScroll); }, []);

const progress = Math.min( (throttledScrollY / (document.body.scrollHeight - window.innerHeight)) * 100, 100 );

return

${progress}% }} />;
}
`
$3
`tsx
import { useThrottle } from "@usefy/use-throttle";
function MouseTracker() {
  const [position, setPosition] = useState({ x: 0, y: 0 });
  const throttledPosition = useThrottle(position, 50);
  useEffect(() => {
    const handleMouseMove = (e: MouseEvent) => {
      setPosition({ x: e.clientX, y: e.clientY });
    };
    window.addEventListener("mousemove", handleMouseMove);
    return () => window.removeEventListener("mousemove", handleMouseMove);
  }, []);
  return (
          className="cursor-follower"
      style={{
        transform: translate(${throttledPosition.x}px, ${throttledPosition.y}px),
      }}
    />
  );
}
`
$3
`tsx
import { useThrottle } from "@usefy/use-throttle";
function ResponsiveLayout() {
  const [windowSize, setWindowSize] = useState({
    width: window.innerWidth,
    height: window.innerHeight,
  });
  const throttledSize = useThrottle(windowSize, 200);
  useEffect(() => {
    const handleResize = () => {
      setWindowSize({
        width: window.innerWidth,
        height: window.innerHeight,
      });
    };
    window.addEventListener("resize", handleResize);
    return () => window.removeEventListener("resize", handleResize);
  }, []);
  const layout = throttledSize.width >= 768 ? "desktop" : "mobile";
  return (
    
layout-${layout}}>
      Window: {throttledSize.width} x {throttledSize.height}
    

  );
}
`
$3
`tsx
import { useThrottle } from "@usefy/use-throttle";
function RangeSlider() {
  const [value, setValue] = useState(50);
  const throttledValue = useThrottle(value, 200);
  // API call only happens at most every 200ms
  useEffect(() => {
    updateServerValue(throttledValue);
  }, [throttledValue]);
  return (
    

              type="range"
        min="0"
        max="100"
        value={value}
        onChange={(e) => setValue(+e.target.value)}
      />
      Value: {throttledValue}
    

  );
}
`
$3
`tsx
import { useThrottle } from "@usefy/use-throttle";
function InstantFeedback() {
  const [clicks, setClicks] = useState(0);
  // Update immediately on first click, ignore subsequent clicks for 500ms
  const throttledClicks = useThrottle(clicks, 500, {
    leading: true,
    trailing: false,
  });
  return (
    
  );
}
`
$3
`tsx
import { useThrottle } from "@usefy/use-throttle";
function DelayedUpdate() {
  const [value, setValue] = useState("");
  // Only update after the interval passes
  const throttledValue = useThrottle(value, 300, {
    leading: false,
    trailing: true,
  });
  return (
    

       setValue(e.target.value)} />
      Throttled: {throttledValue}

    

  );
}
`
---
TypeScript
This hook is written in TypeScript with full generic support.`tsx
import { useThrottle, type UseThrottleOptions } from "@usefy/use-throttle";
// Generic type inference
const throttledString = useThrottle("hello", 300); // string
const throttledNumber = useThrottle(42, 300); // number
const throttledObject = useThrottle({ x: 1 }, 300); // { x: number }
// Options type
const options: UseThrottleOptions = {
  leading: true,
  trailing: false,
};
``
---
Testing
This package maintains comprehensive test coverage to ensure reliability and stability.
$3
📊 View Detailed Coverage Report (GitHub Pages)
$3

Initialization Tests
- Initialize with string, number, boolean, object, array values
- Use default delay of 500ms when not specified

Throttling Behavior Tests
- Update immediately on first change (leading edge)
- Throttle rapid updates after leading edge
- Update at most once per interval during continuous changes
- Allow new leading edge after interval passes

Leading/Trailing Edge Tests
- Update immediately with leading: true (default)
- No immediate update with leading: false
- Update on trailing edge with trailing: true (default)
---
License
MIT © mirunamu
This package is part of the usefy monorepo.
---

  _{Built with care by the usefy team}