String.prototype.includes() — Methode · JavaScript-Referenz

Signatur

String.prototype.includes(searchString, position)

Beschreibung

Mit includes() prüfen Sie, ob ein bestimmter Teil-String irgendwo in einem String vorkommt. Die Methode ist die lesbare Alternative zum älteren Muster str.indexOf(x) !== -1 und eignet sich für einfache Prüfungen: Stichwortsuche, Filterung von Listen oder Validierung von Eingaben.

Die Suche unterscheidet zwischen Groß- und Kleinschreibung: "Blue Whale".includes("blue") ergibt false. Soll die Schreibweise egal sein, wandeln Sie beide Strings vorher mit toLowerCase() (oder toLocaleLowerCase()) in Kleinbuchstaben um.

Mit dem optionalen Parameter position legen Sie fest, ab welchem Index gesucht wird. Ein leerer Such-String liefert immer true. Ist das Argument ein regulärer Ausdruck, wirft die Methode einen TypeError. Für Suchmuster nehmen Sie stattdessen RegExp.prototype.test().

Parameter

Name	Typ	Default	Beschreibung
$searchString Pflicht	string		Der Teil-String, nach dem gesucht wird. Andere Werte werden in einen String umgewandelt (`undefined` wird zu `"undefined"`). Ein `RegExp` führt zu einem `TypeError`.
$position	number	0	Index, ab dem gesucht wird. Negative Werte werden wie `0` behandelt, Werte über der Länge wie `str.length`.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Such-String irgendwo innerhalb des gegebenen Strings gefunden wird, auch wenn searchString ein leerer String ist; andernfalls false.

Beispiele

Einfache Prüfung und Groß-/Kleinschreibung

const satz = "Der schnelle braune Fuchs";

console.log(satz.includes("braune"));
console.log(satz.includes("Braune"));
console.log(satz.toLowerCase().includes("braune".toLowerCase()));
console.log(satz.includes(""));

true false true true

Suche ab einer bestimmten Position

const pfad = "src/components/Button.js";

console.log(pfad.includes("src"));
console.log(pfad.includes("src", 1));
console.log(pfad.includes("Button", -10)); // negativ -> 0

true false true

Live-Filter für eine Produktliste (ohne Groß-/Kleinschreibung)

const produkte = ["Apfelsaft", "Orangensaft", "Mineralwasser", "Apfelschorle"];

const filtern = (liste, suchbegriff) => {
  const begriff = suchbegriff.trim().toLowerCase();
  return liste.filter((name) => name.toLowerCase().includes(begriff));
};

console.log(filtern(produkte, "APFEL"));
console.log(filtern(produkte, "saft"));

[ 'Apfelsaft', 'Apfelschorle' ] [ 'Apfelsaft', 'Orangensaft' ]

Fehler bei regulären Ausdrücken

try {
  "abc123".includes(/\d+/);
} catch (err) {
  console.log(err.name);
}

// Stattdessen:
console.log(/\d+/.test("abc123"));

TypeError true

// Wichtig · Fallstricke

Keine regulären Ausdrücke: Wird ein RegExp übergeben, wirft die Methode einen TypeError. Ausnahme: Das Objekt hat Symbol.match auf false gesetzt. Für Muster verwenden Sie RegExp.prototype.test() oder String.prototype.search().
Typumwandlung: "undefined".includes() ergibt true, weil das fehlende Argument zu "undefined" umgewandelt wird. Prüfen Sie Eingaben deshalb vorher.
Groß-/Kleinschreibung und Unicode: Die Methode vergleicht UTF-16-Code-Einheiten. Bei unterschiedlich normalisierten Zeichen (z. B. "é" als ein Zeichen oder als e plus Akzent) sollten Sie vorher normalize() aufrufen. Für sprachabhängige Vergleiche ist toLocaleLowerCase() sicherer (türkisches İ/ı).
Kompatibilität: Seit ES2015 in allen modernen Browsern und in Node.js verfügbar. Der Internet Explorer unterstützt die Methode nicht; dort braucht man ein Polyfill oder indexOf() !== -1.
Nicht verwechseln mit Array.prototype.includes(): Diese Methode prüft Array-Elemente mit dem SameValueZero-Vergleich, nicht Teil-Strings.

Siehe auch

String.prototype.indexOf() String.prototype.startsWith() String.prototype.endsWith() String.prototype.toLowerCase() RegExp.prototype.test() Array.prototype.includes()