HTMLInputElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLInputElement extends HTMLElement

Beschreibung

HTMLInputElement ist die DOM-Schnittstelle für alle <input>-Elemente, egal ob Textfeld, Checkbox, Radiobutton, Datei-Upload, Datum oder Schieberegler. Sie erbt von HTMLElement und ergänzt Eigenschaften wie value, checked, type, files, valueAsNumber, valueAsDate, disabled, required und placeholder.

Wichtige Methoden sind select(), setSelectionRange() und setRangeText() für die Textauswahl, stepUp() und stepDown() für Zahlen- und Datumsfelder, showPicker() zum Öffnen des nativen Auswahldialogs sowie die Validierungsmethoden checkValidity(), reportValidity() und setCustomValidity() aus der Constraint Validation API. Über validity (ein ValidityState-Objekt) lässt sich genau abfragen, warum ein Feld ungültig ist.

Einsetzen solltest du die Schnittstelle immer dann, wenn du Formulareingaben auslesen, live prüfen, vorbelegen oder dynamisch verändern willst, etwa für eine Validierung auf Clientseite, einen Datei-Upload mit Vorschau oder abhängige Formularfelder. Instanzen bekommst du über document.querySelector('input'), form.elements oder document.createElement('input').

Wichtig: Nicht jede Eigenschaft gilt für jeden type. So wirft setSelectionRange() bei type="email" oder number einen Fehler, und files ist nur bei type="file" gesetzt. Außerdem ist value immer ein String. Für Zahlen oder Daten nimmst du valueAsNumber bzw. valueAsDate.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Aktueller Wert des Feldes, immer als String. Das Setzen per Skript löst kein `input`-Event aus.
$type	string	"text"	Typ des Feldes, z. B. `text`, `email`, `number`, `checkbox`, `file`, `date`, `range`.
$checked	boolean	false	Aktueller Zustand bei `checkbox` und `radio`. `defaultChecked` spiegelt dagegen das HTML-Attribut wider.
$indeterminate	boolean	false	Zeigt eine Checkbox als „teilweise ausgewählt“ an. Das geht nur per Skript, es gibt kein passendes HTML-Attribut.
$files	FileList \| null	null	Die ausgewählten Dateien bei `type="file"`.
$valueAsNumber	number	NaN	Wert als Zahl bei `number`, `range` und Datums-/Zeittypen. Ist das Feld leer, ergibt sich `NaN`.
$valueAsDate	Date \| null	null	Wert als `Date` bei `date`, `time`, `week` und `month` (in UTC).
$validity	ValidityState		Nur lesbar. Beschreibt den Validierungszustand, z. B. `valueMissing`, `typeMismatch`, `patternMismatch`.
$disabled / required / readOnly	boolean	false	Spiegeln die gleichnamigen HTML-Attribute wider und steuern, ob das Feld bearbeitbar ist und in die Validierung eingeht.
$selectionStart / selectionEnd	number \| null		Cursor- bzw. Auswahlposition in Textfeldern. Bei Typen ohne Auswahlunterstützung ist der Wert `null`.

Rückgabewert

Typ

HTMLInputElement

Beschreibung

Eine Referenz auf das <input>-Element, z. B. von document.querySelector() oder document.createElement('input').

Beispiele

Eingabefeld erzeugen und einfügen

const input = document.createElement('input');
input.type = 'email';
input.name = 'email';
input.placeholder = 'name@beispiel.de';
input.required = true;

document.querySelector('form').append(input);
console.log(input instanceof HTMLInputElement, input.type);

true "email"

Live-Validierung mit eigener Fehlermeldung

const pw = document.querySelector('#passwort');

pw.addEventListener('input', () => {
  if (pw.value.length < 8) {
    pw.setCustomValidity('Das Passwort muss mindestens 8 Zeichen lang sein.');
  } else {
    pw.setCustomValidity(''); // Leerer String = gültig
  }
});

document.querySelector('form').addEventListener('submit', (e) => {
  if (!pw.reportValidity()) e.preventDefault();
});

Datei-Upload mit Bildvorschau

const fileInput = document.querySelector('input[type="file"]');
const img = document.querySelector('#vorschau');

fileInput.addEventListener('change', () => {
  const [datei] = fileInput.files;
  if (!datei || !datei.type.startsWith('image/')) return;
  img.src = URL.createObjectURL(datei);
  img.onload = () => URL.revokeObjectURL(img.src);
  console.log(`${datei.name} (${Math.round(datei.size / 1024)} KB)`);
});

urlaub.jpg (245 KB)

Zahlen- und Datumsfelder typsicher auslesen

const menge = document.querySelector('input[type="number"]');
const datum = document.querySelector('input[type="date"]');

menge.value = '3';
menge.stepUp(2);
console.log(menge.valueAsNumber * 9.99);

datum.value = '2024-05-01';
console.log(datum.valueAsDate.toISOString());

49.95 "2024-05-01T00:00:00.000Z"

// Wichtig · Fallstricke

value ist immer ein String: '2' + 1 ergibt '21'. Nutze valueAsNumber oder Number().
Keine Events beim Setzen per Skript: Wenn du value oder checked im Code setzt, werden weder input noch change ausgelöst. Bei Bedarf feuerst du das Event manuell mit el.dispatchEvent(new Event('input', { bubbles: true })).
Eigenschaft und Attribut sind nicht dasselbe: el.value ist der aktuelle Wert, el.getAttribute('value') bzw. defaultValue der Anfangswert. Dasselbe gilt für checked und defaultChecked.
Auswahl-APIs: setSelectionRange() und selectionStart funktionieren nur bei text, search, url, tel und password. Bei email oder number wird ein InvalidStateError geworfen.
setCustomValidity(): Solange die Meldung kein leerer String ist, gilt das Feld als ungültig. Vergisst du das Zurücksetzen, lässt sich das Formular nicht mehr absenden.
showPicker() ist erst in neueren Browsern verfügbar (Chrome 99+, Firefox 101+, Safari 16+). Die Methode braucht eine Nutzeraktion und wirft in Cross-Origin-iframes einen Fehler.
Sicherheit: Die Validierung im Browser ersetzt nie die Prüfung auf dem Server. Eingabewerte gibst du nie ungefiltert über innerHTML aus, sondern über textContent, sonst droht XSS.
Die Grundfunktionen werden von allen Browsern unterstützt. Neuere Typen wie datetime-local, week oder month werden in älteren Safari-Versionen teilweise als text dargestellt.

Siehe auch

HTMLOutputElement HTMLDListElement HTMLFontElement HTMLImageElement HTMLLinkElement HTMLLegendElement HTMLSpanElement