RadioNodeList.value — Eigenschaft · JavaScript-Referenz

Signatur

RadioNodeList.value

Beschreibung

Die Eigenschaft value einer RadioNodeList ist der bequemste Weg, eine Gruppe von Optionsfeldern mit demselben name als einen Wert zu behandeln. Eine RadioNodeList bekommt man über form.elements.namedItem(name) bzw. form.elements[name], wenn mehrere Formularelemente denselben Namen tragen.

Lesen: Zurückgegeben wird der value des ersten ausgewählten Optionsfelds der Liste (in Dokumentreihenfolge). Ist keines ausgewählt, ist das Ergebnis ein leerer String "". Hat das ausgewählte Optionsfeld kein value-Attribut, wird "on" zurückgegeben.

Schreiben: Beim Zuweisen wird das erste Optionsfeld ausgewählt, dessen value-Attribut dem neuen Wert entspricht; die übrigen Felder der Gruppe werden dadurch automatisch abgewählt. Wird kein passendes Feld gefunden, bleibt die Auswahl unverändert. Der Sonderwert "on" trifft zusätzlich auch Optionsfelder ohne value-Attribut.

Elemente in der Liste, die keine Optionsfelder sind (z. B. ein gleichnamiges <input type="text"> oder Kontrollkästchen), werden von value vollständig ignoriert.

Parameter

Name	Typ	Default	Beschreibung
$neuerWert	string		Nur beim Setzen: der `value` des Optionsfelds, das ausgewählt werden soll. Andere Typen werden in einen String umgewandelt.

Rückgabewert

Typ

string

Beschreibung

Der value des ausgewählten Optionsfelds, "on", wenn diesem das value-Attribut fehlt, oder "", wenn nichts ausgewählt ist.

Beispiele

Ausgewählte Versandart auslesen

document.body.insertAdjacentHTML('beforeend', `
  <form id="bestellung">
    <label><input type="radio" name="versand" value="standard" checked> Standard</label>
    <label><input type="radio" name="versand" value="express"> Express</label>
    <label><input type="radio" name="versand" value="abholung"> Abholung</label>
  </form>
`);

const form = document.getElementById('bestellung');
const versand = form.elements.namedItem('versand'); // RadioNodeList

console.log(versand instanceof RadioNodeList);
console.log(versand.value);

true standard

Auswahl per Code setzen (z. B. aus gespeicherten Einstellungen)

document.body.insertAdjacentHTML('beforeend', `
  <form id="einstellungen">
    <input type="radio" name="theme" value="hell" checked>
    <input type="radio" name="theme" value="dunkel">
    <input type="radio" name="theme" value="system">
  </form>
`);

const themes = document.forms.einstellungen.elements.theme;
const gespeichert = localStorage.getItem('theme') ?? 'dunkel';

themes.value = gespeichert;           // wählt das passende Feld aus
console.log(themes.value);

themes.value = 'gibt-es-nicht';       // kein Treffer: Auswahl bleibt
console.log(themes.value);

dunkel dunkel

Auf Änderungen reagieren und Pflichtauswahl prüfen

document.body.insertAdjacentHTML('beforeend', `
  <form id="umfrage">
    <input type="radio" name="bewertung" value="1"> 1
    <input type="radio" name="bewertung" value="2"> 2
    <input type="radio" name="bewertung" value="3"> 3
    <button>Absenden</button>
  </form>
`);

const form = document.forms.umfrage;

form.addEventListener('change', (event) => {
  if (event.target.name === 'bewertung') {
    console.log('Neue Bewertung:', form.elements.bewertung.value);
  }
});

form.addEventListener('submit', (event) => {
  event.preventDefault();
  const wert = form.elements.bewertung.value;
  if (wert === '') {
    console.log('Bitte eine Bewertung auswählen.');
    return;
  }
  console.log('Gesendet:', Number(wert));
});

Bitte eine Bewertung auswählen. (beim Absenden ohne Auswahl)

// Wichtig · Fallstricke

Kein RadioNodeList bei nur einem Element: Gibt es nur ein einziges Element mit dem Namen, liefert form.elements[name] direkt das HTMLInputElement statt einer RadioNodeList. Dessen value ist immer der Attributwert, egal ob ausgewählt oder nicht. Mit instanceof RadioNodeList prüfen oder gezielt form.querySelector('input[name="x"]:checked') verwenden.
Keine Events beim Setzen: Eine Zuweisung an value löst weder change noch input aus. Wenn nötig, das Event manuell mit dispatchEvent(new Event('change', { bubbles: true })) auslösen.
Keine Abwahl möglich: Mit value = '' lässt sich die Auswahl nicht aufheben (außer ein Feld hat tatsächlich value=""). Zum Abwählen checked = false an den einzelnen Elementen setzen oder form.reset() aufrufen.
Der Rückgabewert ist immer ein String, auch bei numerischen Werten – bei Bedarf mit Number() umwandeln.
Kompatibilität: in allen aktuellen Browsern (Chrome, Edge, Firefox, Safari) verfügbar, nicht im Internet Explorer.

Siehe auch

RadioNodeList HTMLFormControlsCollection.namedItem() HTMLFormElement.elements HTMLInputElement.checked MediaTrackConstraints.volume