useWatchWithFilter

Category

Watch

Export Size

314 B

Last Changed

5 days ago

watch with additional EventFilter control

Demo

Usage

Similar to useWatch, but with an eventFilter option that controls if events should be received:

import { useWatchWithFilter } from '@reause/shared'

useWatchWithFilter(
  input,
  () => { console.log('changed!') },
)

Options

Option	Type	Default	Description
eventFilter	EventFilter	bypass (invoke directly)	Filter for if events should be received (captured on mount)
immediate	boolean	false	Fire the callback once on mount with the current value (still filtered)

Event Filters

The filter factories are exported alongside the hook — debounceFilter(ms) and throttleFilter(ms) — mirroring upstream's filter semantics:

import { debounceFilter, throttleFilter, useWatchWithFilter } from '@reause/shared'

// Debounce: bursts of changes collapse into one call 100ms after the last change,
// forced by maxWait when changes never settle
useWatchWithFilter(input, callback, { eventFilter: debounceFilter(100, { maxWait: 500 }) })

// Throttle: at most one call per 100ms window (leading + trailing edges by default)
useWatchWithFilter(scrollY, callback, { eventFilter: throttleFilter(100) })

Stopping the watcher

import { debounceFilter, useWatchWithFilter } from '@reause/shared'

const stop = useWatchWithFilter(source, callback, { eventFilter: debounceFilter(100) })

// further changes — and any pending filtered invocation — won't fire the callback
stop()

Fire the callback once on mount with the current value (still filtered):

import { useWatchWithFilter } from '@reause/shared'

useWatchWithFilter(input, () => console.log('changed!'), { immediate: true })

Type Declarations

Toggle

export type EventFilter = (invoke: FunctionArgs, options?: Record<string, unknown>) => void

export interface CancelableEventFilter extends EventFilter {
    cancel: () => void;
    flush: () => void;
    readonly isPending: boolean;
}

export interface UseWatchWithFilterOptions {
    eventFilter?: EventFilter;
    immediate?: boolean;
}

export type UseWatchWithFilterReturn = () => void

export interface DebounceFilterOptions {
    maxWait?: number;
    rejectOnCancel?: boolean;
}

export interface UseWatchCallback<T = any> {
    (value: T, oldValue: T | undefined): void;
}

export function debounceFilter(ms?: number, options?: DebounceFilterOptions): CancelableEventFilter

export function throttleFilter(ms?: number, trailing?, leading?): EventFilter

export function useWatchWithFilter<T extends any[]>(source: readonly [
    ...T
], callback: UseWatchCallback<[
    ...T
]>, options?: UseWatchWithFilterOptions): UseWatchWithFilterReturn

export function useWatchWithFilter<T>(source: T, callback: UseWatchCallback<T>, options?: UseWatchWithFilterOptions): UseWatchWithFilterReturn

export function useDebounceFn<T extends FunctionArgs>(fn: T, ms?: number, options?: DebounceFilterOptions): UseDebounceFnReturn<T>

export function useWatch<T extends any[]>(source: readonly [
    ...T
], callback: UseWatchCallback<[
    ...T
]>, options?: UseWatchOptions): void

export function useWatch<T>(source: T, callback: UseWatchCallback<T>, options?: UseWatchOptions): void

Source

Source · Demo · VueUse

Contributors

Changelog

v0.1.0 on

80cfb - fix(shared): resolve useWatchWithFilter audit findings (#775)

37fd6 - fix(core): resolve useMouse audit findings (#603)

8fddc - chore!: remove all Vue-only Maybe* types and getter unions, adopt React Ref (#462)