Guide

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

Terminal
npm install @samline/debounce

pnpm

Terminal
pnpm add @samline/debounce

yarn

Terminal
yarn add @samline/debounce

bun

Terminal
bun add @samline/debounce

HTML / CDN

Terminal
<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.

SearchLive preview

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

    index.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

    style.css
    ul {
      padding-left: 1.25rem;
    }
    #status {
      color: #666;
    }
    

    JavaScript

    main.js
    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

    index.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>
        <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

    index.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

    style.css
    ul {
      padding-left: 1.25rem;
    }
    #status {
      color: #666;
    }
    

    JavaScript

    main.js
    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

    index.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>
        <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