useThrottledValue

Function: useThrottledValue()

function useThrottledValue<TValue, TSelected>(
   value, 
   options, 
   selector?): [TValue, ReactThrottler<Dispatch<SetStateAction<TValue>>, TSelected>]

function useThrottledValue<TValue, TSelected>(
   value, 
   options, 
   selector?): [TValue, ReactThrottler<Dispatch<SetStateAction<TValue>>, TSelected>]

Defined in: react-pacer/src/throttler/useThrottledValue.ts:84

A high-level React hook that creates a throttled version of a value that updates at most once within a specified time window. This hook uses React's useState internally to manage the throttled state.

Throttling ensures the value updates occur at a controlled rate regardless of how frequently the input value changes. This is useful for rate-limiting expensive re-renders or API calls that depend on rapidly changing values.

The hook returns a tuple containing:

The throttled value that updates according to the leading/trailing edge behavior specified in the options
The throttler instance with control methods

For more direct control over throttling behavior without React state management, consider using the lower-level useThrottler hook instead.

State Management and Selector

The hook uses TanStack Store for reactive state management via the underlying throttler instance. The selector parameter allows you to specify which throttler state changes will trigger a re-render, optimizing performance by preventing unnecessary re-renders when irrelevant state changes occur.

By default, all throttler 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 throttler state properties:

executionCount: Number of function executions that have been completed
lastArgs: The arguments from the most recent call to maybeExecute
lastExecutionTime: Timestamp of the last function execution in milliseconds
nextExecutionTime: Timestamp when the next execution can occur in milliseconds
isPending: Whether the throttler is waiting for the timeout to trigger execution
status: Current execution status ('disabled' | 'idle' | 'pending')

// Basic throttling - update at most once per second (re-renders on any throttler state change)
const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });

// Only re-render when execution count changes (optimized for tracking executions)
const [throttledValue, throttler] = useThrottledValue(
  rawValue,
  { wait: 1000 },
  (state) => ({ executionCount: state.executionCount })
);

// Only re-render when throttling state changes (optimized for loading indicators)
const [throttledValue, throttler] = useThrottledValue(
  rawValue,
  { wait: 1000 },
  (state) => ({
    isPending: state.isPending,
    status: state.status
  })
);

// Only re-render when timing information changes (optimized for timing displays)
const [throttledValue, throttler] = useThrottledValue(
  rawValue,
  { wait: 1000 },
  (state) => ({
    lastExecutionTime: state.lastExecutionTime,
    nextExecutionTime: state.nextExecutionTime
  })
);

// With custom leading/trailing behavior
const [throttledValue, throttler] = useThrottledValue(rawValue, {
  wait: 1000,
  leading: true,   // Update immediately on first change
  trailing: false  // Skip trailing edge updates
});

// Access the selected throttler state
const { executionCount, isPending } = throttler.state;

// Basic throttling - update at most once per second (re-renders on any throttler state change)
const [throttledValue, throttler] = useThrottledValue(rawValue, { wait: 1000 });

// Only re-render when execution count changes (optimized for tracking executions)
const [throttledValue, throttler] = useThrottledValue(
  rawValue,
  { wait: 1000 },
  (state) => ({ executionCount: state.executionCount })
);

// Only re-render when throttling state changes (optimized for loading indicators)
const [throttledValue, throttler] = useThrottledValue(
  rawValue,
  { wait: 1000 },
  (state) => ({
    isPending: state.isPending,
    status: state.status
  })
);

// Only re-render when timing information changes (optimized for timing displays)
const [throttledValue, throttler] = useThrottledValue(
  rawValue,
  { wait: 1000 },
  (state) => ({
    lastExecutionTime: state.lastExecutionTime,
    nextExecutionTime: state.nextExecutionTime
  })
);

// With custom leading/trailing behavior
const [throttledValue, throttler] = useThrottledValue(rawValue, {
  wait: 1000,
  leading: true,   // Update immediately on first change
  trailing: false  // Skip trailing edge updates
});

// Access the selected throttler state
const { executionCount, isPending } = throttler.state;

useThrottledValue

Function: useThrottledValue()

State Management and Selector

Type Parameters

Parameters

value

options

selector?

Returns

Example

Subscribe to Bytes

Subscribe to Bytes