HTMLInputElement: search — Ereignis · JavaScript-Referenz

Signatur

inputElement.addEventListener("search", handler)

Beschreibung

Das search-Ereignis gibt es nur bei <input>-Elementen mit type="search". Der Browser löst es aus, wenn die Nutzerin eine Suche startet. Das passiert vor allem in drei Fällen:

Sie drückt im Feld die Enter-Taste.
Sie klickt auf die eingebaute Löschen-Schaltfläche (das „×“). Dann ist value ein leerer String.
Das Feld hat das nicht standardisierte Attribut incremental. Dann feuert das Ereignis auch beim Tippen, leicht verzögert (in Chromium ca. 500 ms nach der letzten Taste).

Sie können einen Listener mit addEventListener("search", handler) registrieren oder die Eigenschaft onsearch setzen. Der Handler bekommt ein normales Event-Objekt. Das Ereignis steigt im DOM auf (Bubbling), lässt sich aber nicht abbrechen.

Das Ereignis ist praktisch für einfache Suchfelder ohne umgebendes <form>. Vor allem können Sie damit das Leeren des Feldes über das „×“ erkennen. Das Ereignis ist aber nicht standardisiert und fehlt in Firefox. Für Anwendungen, die in allen Browsern laufen sollen, brauchen Sie deshalb immer einen Ersatz über input, keydown oder submit.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses: `"search"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion, die beim Start einer Suche aufgerufen wird. `event.target.value` enthält den aktuellen Suchbegriff.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `passive`, `capture` oder `signal` (zum Entfernen mit einem `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener hat keinen Rückgabewert. Der Handler bekommt ein Event-Objekt.

Beispiele

Suche mit Enter starten und Leeren über das „×“ erkennen

// HTML: <input type="search" id="suche" placeholder="Artikel suchen …">
const feld = document.querySelector('#suche');

feld.addEventListener('search', (event) => {
  const begriff = event.target.value.trim();
  if (begriff === '') {
    console.log('Suche zurückgesetzt');
    return;
  }
  console.log(`Suche nach: ${begriff}`);
});

Suche nach: javascript Suche zurückgesetzt

Live-Suche mit incremental und onsearch

// HTML: <input type="search" id="filter" incremental>
// <ul id="liste"><li>Apfel</li><li>Birne</li><li>Banane</li></ul>
const filter = document.querySelector('#filter');
const eintraege = [...document.querySelectorAll('#liste li')];

filter.onsearch = () => {
  const q = filter.value.toLowerCase();
  for (const li of eintraege) {
    li.hidden = !li.textContent.toLowerCase().includes(q);
  }
  console.log(`${eintraege.filter((li) => !li.hidden).length} Treffer`);
};

2 Treffer // bei Eingabe "b"

Ersatzlösung für alle Browser und Listener entfernen

const feld = document.querySelector('input[type="search"]');
const controller = new AbortController();

const sucheAusfuehren = async (begriff) => {
  const res = await fetch(`/api/suche?q=${encodeURIComponent(begriff)}`);
  const daten = await res.json();
  console.log(daten.length, 'Ergebnisse');
};

if ('onsearch' in feld) {
  feld.addEventListener('search', () => sucheAusfuehren(feld.value),
    { signal: controller.signal });
} else {
  // Firefox: Enter und Leeren selbst erkennen
  feld.addEventListener('keydown', (e) => {
    if (e.key === 'Enter') sucheAusfuehren(feld.value);
  }, { signal: controller.signal });
  feld.addEventListener('input', () => {
    if (feld.value === '') sucheAusfuehren('');
  }, { signal: controller.signal });
}

// Später, z. B. beim Abbau einer Komponente:
// controller.abort();

12 Ergebnisse

// Wichtig · Fallstricke

Nicht standardisiert: search steht weder im HTML-Standard noch im DOM-Standard. Chromium-Browser und Safari unterstützen es, Firefox nicht. Prüfen Sie die Unterstützung mit 'onsearch' in input und bauen Sie einen Ersatz ein.
Das Attribut incremental ist ebenfalls nicht standardisiert und nur in WebKit/Blink verfügbar. Für eine browserübergreifende Live-Suche verwenden Sie besser input zusammen mit einem eigenen Debounce.
Das Ereignis feuert auch beim Leeren über das „×“. Prüfen Sie im Handler auf einen leeren value, damit keine unnötigen Anfragen mit leerem Suchbegriff ans Backend gehen.
Liegt das Feld in einem <form>, löst Enter zusätzlich submit aus. Ohne event.preventDefault() im submit-Handler lädt die Seite dann neu.
Die Löschen-Schaltfläche fehlt in manchen Browsern oder wurde per CSS entfernt (::-webkit-search-cancel-button). In diesen Fällen feuert das Ereignis nur bei Enter.
Sicherheit: Geben Sie den Suchbegriff nie ungeprüft per innerHTML aus (XSS-Gefahr), sondern mit textContent. In URLs kodieren Sie ihn mit encodeURIComponent.

Siehe auch

HTMLInputElement EventTarget.addEventListener() HTMLElement: command HTMLInputElement: select HTMLInputElement: cancel