useThrottledValue
Return a value limited to once per interval.
Import
TypeScript
import { useThrottledValue } from '@/hooks';API
Signature
useThrottledValue<T>(value, delay | options) → T
When to use
Use useThrottledValue instead of re-implementing the same pattern in multiple components.
SSR / Next.js
SSR-safe. Timers and rAF only run after mount / interactions.
Live playground
Edit the example and see it run against the real @/hooks package in this app.
Live playgroundEdit · run with real
@/hooks · useThrottledValueEditor
function ScrollY({ y }: { y: number }) { const ty = useThrottledValue(y, 100); return <span>y={ty}</span>; }
Preview
Implementation source
Full library source for useThrottledValue — copy into your project when you are not installing a package yet.
hooks/performance/useThrottledValue.ts
import { useEffect, useState } from 'react';
import type { ThrottleOptions } from '../types';
import { useThrottledCallback } from './useThrottledCallback';
/** Returns a throttled copy of `value`. */
export function useThrottledValue<T>(
value: T,
delayOrOptions: number | ThrottleOptions = 300,
): T {
const [throttled, setThrottled] = useState(value);
const update = useThrottledCallback((next: T) => {
setThrottled(next);
}, delayOrOptions);
useEffect(() => {
update(value);
}, [value, update]);
return throttled;
}
Copy-paste example
useThrottledValue.example.tsx
'use client';
import { useThrottledValue } from '@/hooks';
export function ScrollY({ y }: { y: number }) {
const ty = useThrottledValue(y, 100);
return <span>y={ty}</span>;
}Production checklist
- Called only from Client Components or other custom hooks
- Type parameters filled in (e.g.
useFetch<User[]>) - Tip: Stable callbacks prevent child re-renders. Always cancel debounce on unmount (handled for you).
- Source of truth: open
hooks/performance/useThrottledValue.tsfor implementation details