- Docs
- Getting started
Getting started
Install @samline/debounce with a package manager or a script tag and debounce your first handler.
Install @samline/debounce, then follow the Package / ESM or the HTML / CDN path to the first debounced handler. Both use the same API.
Requirements
- Any modern browser. Node 20 or newer for server-side use.
- No runtime dependencies. React, Vue and Svelte are optional peers, only for their adapters.
Install
npm
npm install @samline/debouncepnpm
pnpm add @samline/debounceyarn
yarn add @samline/debouncebun
bun add @samline/debounceHTML / CDN
<script src="https://cdn.jsdelivr.net/npm/@samline/debounce@1.0.2/dist/browser/debounce.global.js" defer></script>Package / ESM
import { debounce } from '@samline/debounce'
const search = debounce(query => fetchResults(query), 300)
input.addEventListener('input', () => search(input.value))
The root entry also exports throttle and rafThrottle. It is ESM and CommonJS (require('@samline/debounce')).
HTML / CDN
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
</script>
Working starter files
A complete page you can save and open: the live preview runs the real package, and its files load the published browser bundle.
debounce waits 300 ms of quiet, Enter runs the pending search at once with flush(), and Escape drops it with cancel().
Type to search.
Explore the code
HTML / CDN
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Search after the user stops typing</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<label for="search">Search a fruit</label>
<input id="search" type="text" autocomplete="off" />
<p id="status" aria-live="polite">Type to search.</p>
<ul id="results"></ul>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/debounce@1.0.2/dist/browser/debounce.global.js"></script>
<script src="./main.js" defer></script>
</body>
</html>
CSS
ul {
padding-left: 1.25rem;
}
#status {
color: #666;
}
JavaScript
const { debounce } = window.Debounce
const fruits = [
'apple',
'apricot',
'banana',
'blueberry',
'cherry',
'grape',
'mango',
'melon',
'orange',
'peach',
'pear',
'plum',
]
const input = document.querySelector('#search')
const status = document.querySelector('#status')
const results = document.querySelector('#results')
const search = debounce(query => {
const matches = fruits.filter(fruit => fruit.includes(query.trim().toLowerCase()))
results.replaceChildren(
...matches.map(fruit => Object.assign(document.createElement('li'), { textContent: fruit }))
)
status.textContent = query.trim()
? `${matches.length} results for “${query.trim()}”`
: 'Type to search.'
}, 300)
input.addEventListener('input', () => search(input.value))
input.addEventListener('keydown', event => {
if (event.key === 'Enter') search.flush()
if (event.key === 'Escape') search.cancel()
})
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Search after the user stops typing</title>
<style>
ul {
padding-left: 1.25rem;
}
#status {
color: #666;
}
</style>
</head>
<body>
<main>
<label for="search">Search a fruit</label>
<input id="search" type="text" autocomplete="off" />
<p id="status" aria-live="polite">Type to search.</p>
<ul id="results"></ul>
</main>
<script src="https://cdn.jsdelivr.net/npm/@samline/debounce@1.0.2/dist/browser/debounce.global.js"></script>
<script>
const { debounce } = window.Debounce
const fruits = [
'apple',
'apricot',
'banana',
'blueberry',
'cherry',
'grape',
'mango',
'melon',
'orange',
'peach',
'pear',
'plum',
]
const input = document.querySelector('#search')
const status = document.querySelector('#status')
const results = document.querySelector('#results')
const search = debounce(query => {
const matches = fruits.filter(fruit => fruit.includes(query.trim().toLowerCase()))
results.replaceChildren(
...matches.map(fruit =>
Object.assign(document.createElement('li'), { textContent: fruit })
)
)
status.textContent = query.trim()
? `${matches.length} results for “${query.trim()}”`
: 'Type to search.'
}, 300)
input.addEventListener('input', () => search(input.value))
input.addEventListener('keydown', event => {
if (event.key === 'Enter') search.flush()
if (event.key === 'Escape') search.cancel()
})
</script>
</body>
</html>
Package / ESM
HTML
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Search after the user stops typing</title>
<link rel="stylesheet" href="./style.css" />
</head>
<body>
<main>
<label for="search">Search a fruit</label>
<input id="search" type="text" autocomplete="off" />
<p id="status" aria-live="polite">Type to search.</p>
<ul id="results"></ul>
</main>
<script type="module" src="./main.js"></script>
</body>
</html>
CSS
ul {
padding-left: 1.25rem;
}
#status {
color: #666;
}
JavaScript
import { debounce } from '@samline/debounce'
const fruits = [
'apple',
'apricot',
'banana',
'blueberry',
'cherry',
'grape',
'mango',
'melon',
'orange',
'peach',
'pear',
'plum',
]
const input = document.querySelector('#search')
const status = document.querySelector('#status')
const results = document.querySelector('#results')
const search = debounce(query => {
const matches = fruits.filter(fruit => fruit.includes(query.trim().toLowerCase()))
results.replaceChildren(
...matches.map(fruit => Object.assign(document.createElement('li'), { textContent: fruit }))
)
status.textContent = query.trim()
? `${matches.length} results for “${query.trim()}”`
: 'Type to search.'
}, 300)
input.addEventListener('input', () => search(input.value))
input.addEventListener('keydown', event => {
if (event.key === 'Enter') search.flush()
if (event.key === 'Escape') search.cancel()
})
Complete file
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Search after the user stops typing</title>
<style>
ul {
padding-left: 1.25rem;
}
#status {
color: #666;
}
</style>
</head>
<body>
<main>
<label for="search">Search a fruit</label>
<input id="search" type="text" autocomplete="off" />
<p id="status" aria-live="polite">Type to search.</p>
<ul id="results"></ul>
</main>
<script type="module">
import { debounce } from '@samline/debounce'
const fruits = [
'apple',
'apricot',
'banana',
'blueberry',
'cherry',
'grape',
'mango',
'melon',
'orange',
'peach',
'pear',
'plum',
]
const input = document.querySelector('#search')
const status = document.querySelector('#status')
const results = document.querySelector('#results')
const search = debounce(query => {
const matches = fruits.filter(fruit => fruit.includes(query.trim().toLowerCase()))
results.replaceChildren(
...matches.map(fruit =>
Object.assign(document.createElement('li'), { textContent: fruit })
)
)
status.textContent = query.trim()
? `${matches.length} results for “${query.trim()}”`
: 'Type to search.'
}, 300)
input.addEventListener('input', () => search(input.value))
input.addEventListener('keydown', event => {
if (event.key === 'Enter') search.flush()
if (event.key === 'Escape') search.cancel()
})
</script>
</body>
</html>
Next steps
Live previews with the complete, copyable source of each one.
API referenceEvery function and its return value.
ConfigurationDefaults and accepted values of leading, trailing and maxWait.
React, Vue and Svelte adapters.