HTMLInputElement.files — Eigenschaft · JavaScript-Referenz

Signatur

HTMLInputElement.files

Beschreibung

Über die Eigenschaft files eines HTMLInputElement greifen Sie auf die Dateien zu, die der Nutzer in einem Dateiauswahlfeld (<input type="file">) ausgewählt hat. Der Wert ist ein FileList-Objekt. Das ist eine arrayähnliche, nur lesbare Liste von File-Objekten. Jedes File enthält unter anderem name, size, type und lastModified und lässt sich mit FileReader, Blob.prototype.text(), arrayBuffer() oder URL.createObjectURL() weiterverarbeiten.

Typische Einsatzfälle sind eine Vorschau von Bildern vor dem Hochladen, eine Prüfung von Dateigröße und Dateityp auf dem Client, das Einlesen lokaler Dateien (etwa CSV oder JSON) direkt im Browser und das Hochladen per fetch() zusammen mit FormData. Mehrere Dateien sind nur möglich, wenn das Attribut multiple gesetzt ist.

Die Eigenschaft ist beschreibbar: Sie können ihr ein anderes FileList-Objekt zuweisen, etwa aus DataTransfer.files nach Drag & Drop. Einen eigenen FileList können Sie nicht direkt anlegen. Der übliche Umweg führt über new DataTransfer() und dessen items.add().

Wenn das Element nicht vom Typ file ist, liefert files den Wert null.

Rückgabewert

Typ

FileList | null

Beschreibung

Ein FileList mit den ausgewählten File-Objekten. Ist nichts ausgewählt, ist die Liste leer (length === 0). Bei Eingabefeldern, die nicht vom Typ file sind, ist der Wert null.

Beispiele

Ausgewählte Dateien auflisten

// HTML: <input type="file" id="upload" multiple>
const input = document.querySelector('#upload');

input.addEventListener('change', () => {
  for (const file of input.files) {
    console.log(`${file.name} – ${(file.size / 1024).toFixed(1)} KB – ${file.type || 'unbekannt'}`);
  }
  console.log(`Anzahl: ${input.files.length}`);
});

bericht.pdf – 245.3 KB – application/pdf foto.jpg – 1024.0 KB – image/jpeg Anzahl: 2

Bildvorschau mit Größenprüfung

// HTML: <input type="file" id="avatar" accept="image/*"> <img id="preview">
const avatar = document.querySelector('#avatar');
const preview = document.querySelector('#preview');
const MAX_BYTES = 2 * 1024 * 1024; // 2 MB

avatar.addEventListener('change', () => {
  const [file] = avatar.files;
  if (!file) return;

  if (file.size > MAX_BYTES) {
    alert('Das Bild darf höchstens 2 MB groß sein.');
    avatar.value = ''; // Auswahl zurücksetzen
    return;
  }

  const url = URL.createObjectURL(file);
  preview.src = url;
  preview.onload = () => URL.revokeObjectURL(url); // Speicher freigeben
});

Dateien per fetch hochladen

// HTML: <input type="file" id="docs" multiple> <button id="send">Hochladen</button>
const docs = document.querySelector('#docs');

document.querySelector('#send').addEventListener('click', async () => {
  if (docs.files.length === 0) {
    console.log('Keine Datei ausgewählt.');
    return;
  }

  const formData = new FormData();
  for (const file of docs.files) {
    formData.append('dokumente[]', file, file.name);
  }

  const response = await fetch('/api/upload', { method: 'POST', body: formData });
  console.log(response.ok ? 'Upload erfolgreich' : `Fehler: ${response.status}`);
});

Upload erfolgreich

Drag & Drop: files neu zuweisen

// HTML: <div id="dropzone">Dateien hierher ziehen</div> <input type="file" id="target" multiple>
const dropzone = document.querySelector('#dropzone');
const target = document.querySelector('#target');

dropzone.addEventListener('dragover', (e) => e.preventDefault());
dropzone.addEventListener('drop', (e) => {
  e.preventDefault();
  target.files = e.dataTransfer.files; // FileList übernehmen
  target.dispatchEvent(new Event('change', { bubbles: true }));
  console.log(`${target.files.length} Datei(en) übernommen`);
});

// Eigene FileList erzeugen, z. B. um eine Datei zu entfernen:
const removeFirst = () => {
  const dt = new DataTransfer();
  [...target.files].slice(1).forEach((f) => dt.items.add(f));
  target.files = dt.files;
};

3 Datei(en) übernommen

// Wichtig · Fallstricke

Kein echtes Array: FileList hat weder map() noch filter(). Iterieren Sie mit for...of oder wandeln Sie die Liste mit Array.from(input.files) bzw. [...input.files] um.
Die Liste ist schreibgeschützt: Einzelne Einträge lassen sich nicht löschen oder ergänzen. Bauen Sie stattdessen über DataTransfer einen neuen FileList und weisen Sie ihn zu. Zum vollständigen Zurücksetzen genügt input.value = ''.
Kein automatisches change-Ereignis: Wenn Sie files per Skript zuweisen, wird kein change-Ereignis ausgelöst. Falls nötig, lösen Sie es selbst aus.
Dieselbe Datei erneut wählen: Wählt der Nutzer dieselbe Datei noch einmal, feuern manche Browser kein change. Abhilfe schafft ein Zurücksetzen von value nach dem Verarbeiten.
Sicherheit: Aus Datenschutzgründen ist der echte lokale Pfad nicht zugänglich (input.value liefert C:\fakepath\…). Prüfungen auf dem Client über type oder size sind reine Komfortfunktionen. Der Wert von type wird nur aus der Dateiendung abgeleitet und muss auf dem Server erneut geprüft werden.
Speicher: Mit URL.createObjectURL() erzeugte URLs sollten Sie mit URL.revokeObjectURL() wieder freigeben.
Kompatibilität: Lesen wird von allen modernen Browsern unterstützt. Das Zuweisen von files und der Konstruktor new DataTransfer() funktionieren in Chrome, Firefox, Edge und Safari (ab 14.1) zuverlässig, aber nicht im Internet Explorer.

Siehe auch

File HTMLInputElement.size HTMLInputElement.alt HTMLInputElement.form HTMLInputElement.labels