PerformanceIntermediateSSR-safehooks/performance/useThrottle.ts

useThrottle

Throttle a changing value.

Import

TypeScript
import { useThrottle } from '@/hooks';

API

Signature

useThrottle<T>(value, delay | options) → T

When to use

Use useThrottle 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 · useThrottle
Editor
function MouseLabel({ x }: { x: number }) {
  const throttledX = useThrottle(x, 100);
  return <span>{throttledX}</span>;
}
Preview

Implementation source

Full library source for useThrottle — copy into your project when you are not installing a package yet.

hooks/performance/useThrottle.ts
import { useThrottledValue } from './useThrottledValue';
import type { ThrottleOptions } from '../types';

/** Alias of {@link useThrottledValue}. */
export function useThrottle<T>(
  value: T,
  delayOrOptions?: number | ThrottleOptions,
): T {
  return useThrottledValue(value, delayOrOptions);
}

Copy-paste example

useThrottle.example.tsx
'use client';

import { useState } from 'react';
import { useThrottle } from '@/hooks';

export function MouseLabel({ x }: { x: number }) {
  const throttledX = useThrottle(x, 100);
  return <span>{throttledX}</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/useThrottle.ts for implementation details