Open History to see the last commit
1---
2id: throttle
3title: throttle
4---
5
6```ts
7function throttle<TFn>(fn, initialOptions): (...args) => void;
8```
9
10Defined in: [throttler.ts:374](https://github.com/TanStack/pacer/blob/main/packages/pacer/src/throttler.ts#L374)
11
12Creates a throttled function that limits how often the provided function can execute.
13
14This synchronous version is lighter weight and often all you need - upgrade to asyncThrottle when you need promises, retry support, abort/cancel capabilities, or advanced error handling.
15
16Throttling ensures a function executes at most once within a specified time window,
17regardless of how many times it is called. This is useful for rate-limiting
18expensive operations or UI updates.
19
20The throttled function can be configured to execute on the leading and/or trailing
21edge of the throttle window via options.
22
23For handling bursts of events, consider using debounce() instead. For hard execution
24limits, consider using rateLimit().
25
26State Management:
27- Uses TanStack Store for reactive state management
28- Use `initialState` to provide initial state values when creating the throttler
29- Use `onExecute` callback to react to function execution and implement custom logic
30- The state includes execution count, last execution time, pending status, and more
31- State can be accessed via the underlying Throttler instance's `store.state` property
32- When using framework adapters (React/Solid), state is accessed from the hook's state property
33
34## Type Parameters
35
36### TFn
37
38`TFn` *extends* [`AnyFunction`](../type-aliases/AnyFunction.md)
39
40## Parameters
41
42### fn
43
44`TFn`
45
46### initialOptions
47
48[`ThrottlerOptions`](../interfaces/ThrottlerOptions.md)\<`TFn`\>
49
50## Returns
51
52```ts
53(...args): void;
54```
55
56Attempts to execute the throttled function. The execution behavior depends on the throttler options:
57
58- If enough time has passed since the last execution (>= wait period):
59 - With leading=true: Executes immediately
60 - With leading=false: Waits for the next trailing execution
61
62- If within the wait period:
63 - With trailing=true: Schedules execution for end of wait period
64 - With trailing=false: Drops the execution
65
66### Parameters
67
68#### args
69
70...`Parameters`\<`TFn`\>
71
72### Returns
73
74`void`
75
76### Example
77
78```ts
79const throttled = new Throttler(fn, { wait: 1000 });
80
81// First call executes immediately
82throttled.maybeExecute('a', 'b');
83
84// Call during wait period - gets throttled
85throttled.maybeExecute('c', 'd');
86```
87
88## Example
89
90```ts
91// Basic throttling - max once per second
92const throttled = throttle(updateUI, { wait: 1000 });
93
94// Configure leading/trailing execution
95const throttled = throttle(saveData, {
96 wait: 2000,
97 leading: true, // Execute immediately on first call
98 trailing: true // Execute again after delay if called during wait
99});
100```