useDebounceValue
Debounced value state with update functionality for React applications. Perfect for Next.js projects requiring optimized input handling with TypeScript support and seamless integration.
Installation
npx shadcn@latest add https://www.shadcn.io/registry/use-debounce-value.jsonnpx shadcn@latest add https://www.shadcn.io/registry/use-debounce-value.jsonpnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-debounce-value.jsonbunx shadcn@latest add https://www.shadcn.io/registry/use-debounce-value.jsonFeatures
- Debounced value state with configurable delay timing for optimized performance
- Function initializer support accepting both direct values and lazy initialization functions
- Advanced debouncing options including leading, trailing, maxWait, and custom equality functions
- TypeScript generics supporting any value type with complete type inference and safety
- Automatic equality checking with customizable comparison functions for complex objects
- Built on useDebounceCallback leveraging existing debounce infrastructure for consistency
Examples
Multiple Debounced Inputs
Comprehensive demo showing different use cases: search with results, username validation, counter batching, and slider performance optimization.
Use Cases
This free open source React hook works well for:
- Search input optimization - Debounce search queries to reduce API calls with Next.js and TypeScript
- Form validation - Delay expensive validation until user stops typing using React state patterns
- Auto-save functionality - Batch save operations with configurable delays and JavaScript optimization
- Slider and range inputs - Smooth performance for continuous value changes with shadcn/ui components
- API request batching - Reduce server load by debouncing rapid value changes in React applications
- Real-time previews - Optimize preview updates with Tailwind CSS styling and debounced rendering
API Reference
useDebounceValue
useDebounceValue<T>(
initialValue: T | (() => T),
delay: number,
options?: UseDebounceValueOptions<T>
): [T, DebouncedState<(value: T) => void>]Parameters
| Parameter | Type | Description |
|---|---|---|
initialValue | T | (() => T) | The initial value or a function that returns the initial value |
delay | number | The delay in milliseconds before the value updates (default 500ms) |
options | UseDebounceValueOptions<T> | Optional configurations for debouncing behavior |
Options
| Option | Type | Default | Description |
|---|---|---|---|
leading | boolean | false | Invoke on the leading edge of the timeout |
trailing | boolean | true | Invoke on the trailing edge of the timeout |
maxWait | number | undefined | Maximum time function is allowed to be delayed |
equalityFn | (left: T, right: T) => boolean | === | Function to determine if value has changed |
Return Value
Returns an array with two elements:
| Index | Type | Description |
|---|---|---|
[0] | T | The current debounced value |
[1] | DebouncedState<(value: T) => void> | Function to update the value with debouncing |
Implementation Notes
- Hook uses useRef to track previous values and prevent unnecessary updates when values are equal
- Supports function initializers for lazy initialization similar to useState patterns
- Custom equality function allows for deep comparison of objects and arrays when needed
- Built on top of useDebounceCallback ensuring consistent debouncing behavior across hooks
- Automatically handles initial value changes by comparing with previous values using equality function
- Compatible with all TypeScript strict mode settings and provides full type inference for generic types
useDebounceCallback
React hook for debouncing callback functions with advanced control options. Perfect for React applications requiring performance optimization with Next.js integration and TypeScript support.
useDocumentTitle
Dynamic document title management for React applications. Perfect for Next.js projects requiring browser tab updates with TypeScript support and seamless integration.