HTMLImageElement.src — Eigenschaft · JavaScript-Referenz

Signatur

HTMLImageElement.src

Beschreibung

Die Eigenschaft src eines HTMLImageElement spiegelt das HTML-Attribut src des <img>-Elements wider. Beim Lesen liefert sie immer eine absolute, aufgelöste URL, auch wenn im Attribut ein relativer Pfad steht. Den Originalwert bekommen Sie mit img.getAttribute("src").

Wenn Sie src setzen, startet der Browser sofort das Laden des neuen Bildes, auch bei Elementen, die noch nicht im DOM hängen. Deshalb eignet sich new Image() zusammen mit src gut, um Bilder vorzuladen. Ob das Laden geklappt hat, erfahren Sie über die Ereignisse load und error oder über die Methode decode(), die ein Promise zurückgibt.

Neben normalen HTTP(S)-URLs sind auch data:-URLs (z. B. Base64-kodierte Bilder) und blob:-URLs aus URL.createObjectURL() erlaubt. Sind zusätzlich srcset oder ein umgebendes <picture> vorhanden, wählt der Browser unter Umständen eine andere Quelle aus. Welches Bild tatsächlich angezeigt wird, verrät dann nur currentSrc.

Parameter

Name	Typ	Default	Beschreibung
$wert	string	""	Beim Setzen: absolute oder relative URL, `data:`-URL oder `blob:`-URL des Bildes. Relative URLs werden gegen die Basis-URL des Dokuments aufgelöst.

Rückgabewert

Typ

string

Beschreibung

Die vollständig aufgelöste, absolute URL des Bildes. Fehlt das Attribut, ist der Rückgabewert ein leerer String "".

Beispiele

Bildquelle lesen und ändern

// HTML: <img id="logo" src="img/logo.png" alt="Logo">
const logo = document.querySelector('#logo');

console.log(logo.src);                 // absolute URL
console.log(logo.getAttribute('src')); // Originalwert aus dem Attribut

// Bild austauschen, z. B. für den Dark Mode
logo.src = 'img/logo-dark.png';

https://example.com/img/logo.png img/logo.png

Bild vorladen mit Promise und Fehlerbehandlung

const loadImage = (url) => new Promise((resolve, reject) => {
  const img = new Image();
  img.addEventListener('load', () => resolve(img), { once: true });
  img.addEventListener('error', () => reject(new Error(`Bild nicht ladbar: ${url}`)), { once: true });
  img.src = url; // src erst nach den Listenern setzen
});

try {
  const img = await loadImage('https://picsum.photos/400/300');
  img.alt = 'Zufallsbild';
  document.body.append(img);
  console.log('Geladen:', img.naturalWidth, 'x', img.naturalHeight);
} catch (err) {
  console.error(err.message);
}

Geladen: 400 x 300

Vorschau einer hochgeladenen Datei über eine blob:-URL

// HTML: <input type="file" id="upload" accept="image/*"> <img id="preview" alt="Vorschau">
const input = document.querySelector('#upload');
const preview = document.querySelector('#preview');

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

  if (preview.src.startsWith('blob:')) URL.revokeObjectURL(preview.src); // alten Speicher freigeben
  preview.src = URL.createObjectURL(file);
  await preview.decode();
  console.log('Vorschau bereit:', preview.src);
});

Vorschau bereit: blob:https://example.com/3f1c…

Fallback-Bild bei Ladefehler

const img = document.querySelector('img.avatar');
const fallback = '/img/avatar-default.svg';

img.addEventListener('error', () => {
  // Endlosschleife verhindern, falls auch das Fallback fehlt
  if (!img.src.endsWith(fallback)) img.src = fallback;
});

// Wichtig · Fallstricke

Absolute URL beim Lesen: img.src === 'bild.png' ist praktisch nie true. Vergleichen Sie mit getAttribute('src') oder mit new URL('bild.png', document.baseURI).href.
srcset / <picture>: src zeigt nicht zuverlässig, welches Bild gerade angezeigt wird. Dafür gibt es currentSrc.
Listener vor src registrieren: Liegt ein Bild im Cache, kann es sehr schnell geladen sein. Hängen Sie load/error daher vor dem Setzen von src an, oder prüfen Sie zusätzlich img.complete.
Gleiche URL: Setzen Sie denselben Wert erneut, lädt der Browser meist nicht nach. Ein Neuladen erzwingen Sie z. B. mit einem Query-Parameter (?v=Date.now()).
Leerer String: img.src = '' löst in modernen Browsern ein error-Ereignis aus. Zum Entfernen besser removeAttribute('src') verwenden.
Speicherlecks: blob:-URLs geben Sie mit URL.revokeObjectURL() wieder frei, sobald sie nicht mehr gebraucht werden.
Sicherheit/CORS: Bilder von fremden Domains lassen sich anzeigen, machen ein <canvas> aber „tainted“. Soll getImageData()/toDataURL() funktionieren, muss crossOrigin vor src gesetzt werden und der Server passende CORS-Header senden. Die CSP-Direktive img-src kann Quellen (auch data:/blob:) blockieren. URLs aus Benutzereingaben setzen Sie besser über src als über innerHTML, sonst droht XSS.
Kompatibilität: Wird von allen Browsern unterstützt. decode() gibt es in allen modernen Browsern.

Siehe auch

HTMLImageElement.alt HTMLImageElement.srcset HTMLImageElement.x HTMLImageElement.y HTMLImageElement.hspace