Tiny debounce, throttle and rafThrottle with cancel(), flush() and pending(), for vanilla JavaScript, React, Vue, Svelte and plain HTML. They forward this, return the last result and never throw outside the browser.
Demo · Examples · Documentation · Changelog
- Installation
- Quick start
- HTML / CDN
- Capabilities
- API at a glance
- Documentation
- Changelog
- AI agent skill
- License
npm install @samline/debouncepnpm add @samline/debouncebun add @samline/debounceWorks in any modern browser and in Node 20 or newer. No runtime dependencies; React, Vue and Svelte are optional peers, needed only for their adapters.
import { debounce, rafThrottle, throttle } from '@samline/debounce'
// Search 250 ms after the user stops typing.
const search = debounce(query => fetchResults(query), 250)
input.addEventListener('input', () => search(input.value))
form.addEventListener('submit', () => search.flush()) // do not wait
window.addEventListener('pagehide', () => search.cancel())
// Save at most once per second while typing.
const save = throttle(() => persist(state), 1000)
// Measure once per frame, whatever the event rate.
const measure = rafThrottle(() => updateLayout(element.getBoundingClientRect()))
window.addEventListener('scroll', measure, { passive: true })For Shopify, WordPress or plain HTML pages without a build step, load the browser bundle with a classic script tag. Pin the version in production.
<script src="https://cdn.jsdelivr.net/npm/@samline/debounce@1.0.2/dist/browser/debounce.global.js"></script>
<script>
const { debounce, throttle, rafThrottle } = window.Debounce
const search = debounce(query => console.log('search', query), 250)
document.querySelector('input').addEventListener('input', event => search(event.target.value))
</script>The bundle defines window.Debounce with debounce, throttle, rafThrottle and the deprecated createDebounce alias.
debounce waits for quiet, throttle keeps a steady rate and rafThrottle runs once per animation frame. Every returned function has cancel(), flush() and pending(), forwards this and returns the last result.
leading, trailing and maxWait follow the lodash semantics. maxWait lower than wait is clamped to wait, invalid waits become 0, and a single call with both edges enabled runs once.
- React:
useDebouncedCallbackanduseThrottledCallbackreturn a stable function that calls the latest callback, is recreated only whenwaitor an option changes, and is cancelled on unmount.useDebouncedValue(value, wait)returns the settled value. - Vue:
useDebouncedCallback,useThrottledCallbackanduseDebouncedRef(source, wait), cancelled when the effect scope is disposed. - Svelte:
createDebouncedStore(initial, wait)withflush()andcancel(); chainedupdatecalls see the latest pending value.
createDebouncestill works but is deprecated; usedebounce.debouncenow forwardsthis, returns the last result and addspending().maxWaitlower thanwaitis clamped towait(it used to fire early).- Svelte's
createDebouncedStorefixes chainedupdatecalls and addsflush()andcancel(). - React's
useDebouncedCallbacknow picks up changes towaitand options. - New:
throttle,rafThrottle,useThrottledCallbackand a CommonJS build.
| API | Purpose |
|---|---|
debounce(fn, wait?, { leading, trailing, maxWait }) |
Run fn once the calls stop for wait ms. |
throttle(fn, wait?, { leading, trailing }) |
Run fn at most once every wait ms. |
rafThrottle(fn) |
Run fn at most once per animation frame. |
.cancel() / .flush() / .pending() |
Drop, run now or inspect the pending invocation. |
| Entrypoint | When to use |
|---|---|
@samline/debounce |
ESM or CommonJS: debounce, throttle, rafThrottle. |
@samline/debounce/vanilla |
The same API as an explicit subpath. |
@samline/debounce/react |
useDebouncedCallback, useThrottledCallback, useDebouncedValue. |
@samline/debounce/vue |
useDebouncedCallback, useThrottledCallback, useDebouncedRef. |
@samline/debounce/svelte |
createDebouncedStore. |
@samline/debounce/browser |
Classic script that defines window.Debounce. |
Read the documentation for the full guides and API contracts, and explore working examples with complete and separate source files.
| Guide | What it covers |
|---|---|
| Installation | npm, CDN and the first debounced handler. |
| API reference | Every function, its return value and the browser global. |
| Options | leading, trailing, maxWait and the lifecycle. |
| Frameworks | React, Vue and Svelte adapters. |
Read CHANGELOG.md or the published changelog for release history and explicitly marked breaking and behavior changes. Review the notes before upgrading.
The Debounce skill teaches verified package integration. Its maintained repository source and website download are the same file. Verify the installed package version before applying its guidance.
Download SKILL.md into a debounce/ folder in your agent's supported skill directory. For agents that discover project skills from .agents/skills/:
mkdir -p .agents/skills/debounce
curl --fail --location https://samline.github.io/debounce/skills/debounce/SKILL.md \
--output .agents/skills/debounce/SKILL.mdKeep the filename SKILL.md; discovery paths and invocation syntax depend on the agent.
MIT — LICENSE.md.