function useThrottler<TFn, TSelected>(
fn,
options,
selector?): ReactThrottler<TFn, TSelected>
function useThrottler<TFn, TSelected>(
fn,
options,
selector?): ReactThrottler<TFn, TSelected>
Defined in: react-pacer/src/throttler/useThrottler.ts:101
A low-level React hook that creates a Throttler instance that limits how often the provided function can execute.
This hook is designed to be flexible and state-management agnostic - it simply returns a throttler instance that you can integrate with any state management solution (useState, Redux, Zustand, Jotai, etc). For a simpler and higher-level hook that integrates directly with React's useState, see useThrottledState.
Throttling ensures a function executes at most once within a specified time window, regardless of how many times it is called. This is useful for rate-limiting expensive operations or UI updates.
The hook uses TanStack Store for reactive state management. The selector parameter allows you to specify which state changes will trigger a re-render, optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.
By default, all state changes will trigger a re-render. To optimize performance, you can provide a selector function that returns only the specific state values your component needs. The component will only re-render when the selected values change.
Available state properties:
• TFn extends AnyFunction
• TSelected = ThrottlerState<TFn>
TFn
ThrottlerOptions<TFn>
(state) => TSelected
ReactThrottler<TFn, TSelected>
// Basic throttling with custom state - re-renders on any state change
const [value, setValue] = useState(0);
const throttler = useThrottler(setValue, { wait: 1000 });
// Only re-render when execution count changes (optimized for tracking executions)
const [value, setValue] = useState(0);
const throttler = useThrottler(
setValue,
{ wait: 1000 },
(state) => ({ executionCount: state.executionCount })
);
// Only re-render when throttling state changes (optimized for loading indicators)
const [value, setValue] = useState(0);
const throttler = useThrottler(
setValue,
{ wait: 1000 },
(state) => ({
isPending: state.isPending,
status: state.status
})
);
// Only re-render when timing information changes (optimized for timing displays)
const [value, setValue] = useState(0);
const throttler = useThrottler(
setValue,
{ wait: 1000 },
(state) => ({
lastExecutionTime: state.lastExecutionTime,
nextExecutionTime: state.nextExecutionTime
})
);
// With any state manager
const throttler = useThrottler(
(value) => stateManager.setState(value),
{
wait: 2000,
leading: true, // Execute immediately on first call
trailing: false // Skip trailing edge updates
}
);
// Access the selected state
const { executionCount, isPending } = throttler.state;
// Basic throttling with custom state - re-renders on any state change
const [value, setValue] = useState(0);
const throttler = useThrottler(setValue, { wait: 1000 });
// Only re-render when execution count changes (optimized for tracking executions)
const [value, setValue] = useState(0);
const throttler = useThrottler(
setValue,
{ wait: 1000 },
(state) => ({ executionCount: state.executionCount })
);
// Only re-render when throttling state changes (optimized for loading indicators)
const [value, setValue] = useState(0);
const throttler = useThrottler(
setValue,
{ wait: 1000 },
(state) => ({
isPending: state.isPending,
status: state.status
})
);
// Only re-render when timing information changes (optimized for timing displays)
const [value, setValue] = useState(0);
const throttler = useThrottler(
setValue,
{ wait: 1000 },
(state) => ({
lastExecutionTime: state.lastExecutionTime,
nextExecutionTime: state.nextExecutionTime
})
);
// With any state manager
const throttler = useThrottler(
(value) => stateManager.setState(value),
{
wait: 2000,
leading: true, // Execute immediately on first call
trailing: false // Skip trailing edge updates
}
);
// Access the selected state
const { executionCount, isPending } = throttler.state;
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.