Ninja Pirate Marksman

    @react-hook/debounce
    TypeScript icon, indicating that this package has built-in type declarations

    4.0.0 • Public • Published

    useDebounce()

    Bundlephobia Types Build status NPM Version MIT License

    npm i @react-hook/debounce

    A React hook for debouncing setState and other callbacks

    Quick Start

    import {useDebounce, useDebounceCallback} from '@react-hook/debounce'
    
    const Component = (props) => {
      // at a basic level, used just like useState
      const [value, setValue] = useDebounce('initialValue')
    }
    
    const useMyCallback = (initialState, wait, leading) => {
      // this is the same code useDebounce() uses to debounce setState
      const [state, setState] = useState(initialState)
      return [state, useDebounceCallback(setState, wait, leading)]
    }

    API

    useDebounce(initialState, wait?, leading?)

    A hook that acts just like React.useState, but with a setState function that is only invoked after the wait time in ms has been exceeded between calls.

    export const useDebounce = <State>(
      initialState: State | (() => State),
      wait?: number,
      leading?: boolean
    ): [State, Dispatch<SetStateAction<State>>]

    Options

    Property Type Default Description
    initialState State | (() => State) The initial state provided to React.useState
    wait number 100 The amount of time in ms you want to wait after the latest call before setting a new state.
    leading boolean false Calls setState on the leading edge (right away). When false, setState will not be called until the next frame is due

    Returns [state, setStateDebounced, setStateImmediate]

    Variable Type Description
    state State The current value in state
    setStateDebounced Function A debounced setState callback
    setStateImmediate Function The regular, immediate setState callback

    Note: Using setStateImmediate does not cancel a queued setStateDebounced calls, i.e., the setStateDebounced will still take effect once its wait time is over. If needed, cancelling behavior could typically still be achieved by calling both setStateImmediate and setStateDebounced with the same value.


    useDebounceCallback(callback, wait?, leading?)

    A hook that will invoke its callback only after wait time in ms has been exceeded between calls.

    export const useDebounceCallback = <CallbackArgs extends any[]>(
      callback: (...args: CallbackArgs) => void,
      wait = 100,
      leading = false
    ): ((...args: CallbackArgs) => void)

    Options

    Property Type Default Description
    callback (...args: CallbackArgs) => void This is the callback you want to debounce. You need to wrap closures/unstable callbacks in useCallback() so that they are stable, otherwise throttling will break between renders.
    wait number 100 Defines the amount of time you want setState to wait after the last received action before executing
    leading boolean false Calls setState on the leading edge (right away). When false, setState will not be called until the next frame is due

    Returns debouncedCallback

    Variable Type Description
    debouncedCallback (...args: CallbackArgs) => void A debounced version of your callback

    LICENSE

    MIT

    Install

    npm i @react-hook/debounce

    DownloadsWeekly Downloads

    84,758

    Version

    4.0.0

    License

    MIT

    Unpacked Size

    37.6 kB

    Total Files

    24

    Last publish

    Collaborators

    • jaredlunde