HTMLSourceElement.width — Eigenschaft · JavaScript-Referenz

Signatur

HTMLSourceElement.width

Beschreibung

Die Eigenschaft width des Interfaces HTMLSourceElement ist eine nicht-negative Ganzzahl. Sie gibt die Breite der Bildressource in CSS-Pixeln an und spiegelt das HTML-Attribut width des <source>-Elements direkt wider. Wenn Sie die Eigenschaft lesen, wird das Attribut ausgewertet. Wenn Sie sie setzen, wird das Attribut geschrieben.

Wirkung hat der Wert nur, wenn das <source>-Element in einem <picture>-Element steht. Wählt der Browser diese Quelle aus, verwendet das zugehörige <img> ihre Werte für width und height. Daraus ergibt sich das Seitenverhältnis, und der Browser kann den Platz reservieren, bevor das Bild geladen ist. So werden Layoutverschiebungen (Cumulative Layout Shift, CLS) vermieden, auch wenn die Varianten der Art Direction unterschiedliche Seitenverhältnisse haben, zum Beispiel Hochformat auf dem Smartphone und Querformat auf dem Desktop.

Innerhalb von <video> oder <audio> wird das Attribut ignoriert. Fehlt das Attribut oder ist sein Wert ungültig, liefert die Eigenschaft 0.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0	Nur beim Setzen: nicht-negative Ganzzahl (Breite in CSS-Pixeln). Nachkommastellen werden abgeschnitten, der Wert landet als Zeichenkette im Attribut `width`.

Rückgabewert

Typ

number

Beschreibung

Die Breite in CSS-Pixeln als nicht-negative Ganzzahl (unsigned long). Fehlt das Attribut oder ist es ungültig, ist der Wert 0.

Beispiele

Breite einer Quelle im picture-Element auslesen

// HTML:
// <picture>
//   <source id="mobil" media="(max-width: 600px)" srcset="hoch.webp" width="400" height="600">
//   <img src="quer.jpg" width="1200" height="600" alt="Landschaft">
// </picture>

const source = document.querySelector('#mobil');
console.log(source.width);  // Zahl, kein String
console.log(source.height);
console.log(`Seitenverhältnis: ${source.width / source.height}`);

400 600 Seitenverhältnis: 0.6666666666666666

Art-Direction-Quellen dynamisch erzeugen (ohne Layoutverschiebung)

const varianten = [
  { media: '(max-width: 600px)', srcset: 'hero-hoch.avif', width: 480, height: 720 },
  { media: '(max-width: 1024px)', srcset: 'hero-quadrat.avif', width: 800, height: 800 }
];

const picture = document.createElement('picture');

for (const v of varianten) {
  const source = document.createElement('source');
  source.media = v.media;
  source.srcset = v.srcset;
  source.width = v.width;   // setzt das Attribut width
  source.height = v.height;
  picture.append(source);
}

const img = document.createElement('img');
img.src = 'hero-quer.jpg';
img.width = 1600;
img.height = 900;
img.alt = 'Titelbild';
picture.append(img);

document.body.append(picture);
console.log(picture.querySelector('source').outerHTML);

Verhalten bei fehlendem oder ungültigem Attribut

const source = document.createElement('source');
console.log(source.width);                 // kein Attribut gesetzt

source.setAttribute('width', 'breit');
console.log(source.width);                 // ungültiger Wert

source.width = 320.9;
console.log(source.width, source.getAttribute('width'));

0 0 320 "320"

// Wichtig · Fallstricke

Wirkt nur in <picture>: In <video> und <audio> hat width keinen Einfluss auf die Darstellung. Die Größe eines Videos steuern Sie über HTMLVideoElement.width oder über CSS.
Keine tatsächliche Bildgröße: Die Eigenschaft liefert nur den Attributwert, nicht die echten Pixelmaße der geladenen Datei. Die natürliche Breite des tatsächlich angezeigten Bildes erhalten Sie über img.naturalWidth, welche Quelle der Browser gewählt hat, über img.currentSrc.
Standardwert 0: Fehlt das Attribut oder ist sein Wert ungültig, wird 0 zurückgegeben. Prüfen Sie mit hasAttribute('width'), ob überhaupt eine Breite angegeben wurde.
Negative Werte: Da es sich um einen unsigned long handelt, werden negative oder sehr große Werte nicht wie erwartet gespeichert und beim Lesen als 0 gewertet.
CSS hat Vorrang: Wird die Breite des <img> per CSS gesetzt (z. B. width: 100%; height: auto), bestimmen width und height nur noch das Seitenverhältnis, nicht die dargestellte Größe.
Browserunterstützung: width und height auf <source> werden erst in neueren Versionen unterstützt, etwa ab Chrome/Edge 90, Safari 15 und Firefox 108. Ältere Browser ignorieren die Werte. Setzen Sie deshalb immer auch width und height am Fallback-<img>.

Siehe auch

HTMLSourceElement.media HTMLSourceElement.sizes HTMLSourceElement.height HTMLSourceElement.src HTMLSourceElement.type