Signatur
Beschreibung
setRangeText() ersetzt Text in einem Eingabefeld, ohne dass du den ganzen value selbst zerlegen und neu zusammensetzen musst. Rufst du die Methode nur mit dem Ersatztext auf, wird die aktuelle Auswahl (bzw. die Cursor-Position) ersetzt. Mit start und end gibst du einen beliebigen Bereich an.
Typische Einsatzfälle sind Editor-Funktionen wie „Text fett markieren“ in Markdown-Feldern, Emoji- oder Platzhalter-Einfügen an der Cursor-Position, Autovervollständigung oder Formatierungshilfen. Anders als ein direktes Setzen von value bleibt die Cursor-Position dabei kontrollierbar: Über selectMode legst du fest, ob der neue Text markiert wird, der Cursor davor bzw. dahinter landet oder die alte Auswahl erhalten bleibt.
Die Methode gibt es auch auf HTMLTextAreaElement. Bei <input> funktioniert sie nur für Typen mit Textauswahl: text, search, url, tel, password. Bei anderen Typen (z. B. email, number) wird eine InvalidStateError-DOMException ausgelöst.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $replacement Pflicht | string | Der Text, der eingefügt wird. | |
| $start | number | selectionStart | Index (nullbasiert) des ersten zu ersetzenden Zeichens. Werte größer als die Textlänge werden auf die Länge begrenzt. |
| $end | number | selectionEnd | Index hinter dem letzten zu ersetzenden Zeichen. Ist start größer als end, wird ein IndexSizeError ausgelöst. |
| $selectMode | "select" | "start" | "end" | "preserve" | "preserve" | Auswahl nach dem Ersetzen: "select" markiert den neuen Text, "start" setzt den Cursor davor, "end" dahinter, "preserve" versucht die bisherige Auswahl zu erhalten. |
Beispiele
Einfacher Fall: Bereich ersetzen
const input = document.createElement('input');
input.value = 'Hallo Welt';
// Zeichen 6 bis 10 ("Welt") ersetzen und neuen Text markieren
input.setRangeText('JavaScript', 6, 10, 'select');
console.log(input.value);
console.log(input.selectionStart, input.selectionEnd);Emoji an der Cursor-Position einfügen
const textarea = document.querySelector('#nachricht');
const button = document.querySelector('#emoji-btn');
button.addEventListener('click', () => {
// Ersetzt die aktuelle Auswahl bzw. fügt am Cursor ein
textarea.setRangeText('😀', textarea.selectionStart, textarea.selectionEnd, 'end');
textarea.focus();
// Frameworks/Validierung über die Änderung informieren
textarea.dispatchEvent(new Event('input', { bubbles: true }));
});Markdown-Editor: Auswahl fett formatieren
const wrapSelection = (el, before, after = before) => {
const { selectionStart: start, selectionEnd: end, value } = el;
const selected = value.slice(start, end) || 'Text';
el.setRangeText(`${before}${selected}${after}`, start, end, 'select');
// Nur den inneren Text markieren
el.setSelectionRange(start + before.length, start + before.length + selected.length);
el.focus();
};
const editor = document.querySelector('textarea');
editor.addEventListener('keydown', (e) => {
if ((e.ctrlKey || e.metaKey) && e.key === 'b') {
e.preventDefault();
wrapSelection(editor, '**');
}
});// Wichtig · Fallstricke
- Kein
input-Event:setRangeText()löst wederinputnochchangeaus. Frameworks wie React oder Vue bemerken die Änderung daher nicht automatisch – das Event bei Bedarf selbst mitdispatchEvent()auslösen. - Kein Undo: Die Änderung landet in den meisten Browsern nicht im Rückgängig-Verlauf (Strg+Z). Soll Undo funktionieren, bleibt oft nur das veraltete
document.execCommand('insertText'). - Nicht unterstützte Typen: Bei
type=\"email\",\"number\",\"date\"usw. wird einInvalidStateErrorausgelöst. Vorher den Typ prüfen oder intry/catchaufrufen. - Nur Ersetzungstext: Mit nur einem Argument wird die aktuelle Auswahl benutzt; ohne vorherigen Fokus steht der Cursor oft am Textende.
maxlengthwird nicht durchgesetzt – der Wert kann dadurch länger werden als erlaubt.- Browser-Unterstützung: Chrome, Edge, Firefox und Safari unterstützen die Methode seit Jahren; der Internet Explorer nicht.