HTMLInputElement.stepUp() — Methode · JavaScript-Referenz

Signatur

HTMLInputElement.prototype.stepUp(stepIncrement)

Beschreibung

stepUp() erhöht den Wert eines <input>-Elements programmgesteuert um ein Vielfaches seines Schrittwerts. Grundlage ist das step-Attribut. Fehlt es, gilt der Standardwert des jeweiligen Typs: 1 bei number und range, 1 Tag bei date, 1 Monat bei month, 1 Woche bei week und 60 Sekunden bei time und datetime-local.

Die Methode funktioniert nur bei den Typen number, range, date, month, week, time und datetime-local. Sie eignet sich für eigene Plus-Schaltflächen, für Tastaturkürzel und für Datumsnavigation, etwa „nächste Woche“. Der Browser beachtet dabei min, max und die Schrittbasis. Du musst also nicht selbst runden oder begrenzen.

Das Verhalten im Einzelnen:

Ist das Feld leer, rechnet der Browser mit 0 bzw. dem Standardwert des Typs weiter.
Liegt der Wert nicht auf dem Schrittraster, rundet der Browser auf den nächsten gültigen Rasterwert in Schrittrichtung.
Würde der neue Wert max überschreiten, setzt der Browser ihn auf den größten gültigen Wert unterhalb von max.
Ein negativer stepIncrement verringert den Wert, genau wie stepDown().

Parameter

Name	Typ	Default	Beschreibung
$stepIncrement	number	1	Multiplikator für den Schrittwert. Bei `step="5"` und `stepIncrement = 3` steigt der Wert um 15. Negative Werte verringern den Wert.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Die Methode ändert direkt value, valueAsNumber bzw. valueAsDate des Elements.

Beispiele

Eigene Plus-/Minus-Schaltflächen für eine Mengenangabe

// HTML: <input id="menge" type="number" min="1" max="10" value="1">
//       <button id="plus">+</button> <button id="minus">−</button>
const menge = document.querySelector('#menge');

const aendern = (richtung) => {
  richtung > 0 ? menge.stepUp() : menge.stepDown();
  // stepUp() löst kein Ereignis aus – selbst melden:
  menge.dispatchEvent(new Event('input', { bubbles: true }));
  menge.dispatchEvent(new Event('change', { bubbles: true }));
};

document.querySelector('#plus').addEventListener('click', () => aendern(1));
document.querySelector('#minus').addEventListener('click', () => aendern(-1));

menge.addEventListener('input', () => console.log('Menge:', menge.valueAsNumber));

Menge: 2 Menge: 3 … (beim Wert 10 bleibt es bei 10, weil max erreicht ist)

Mit Multiplikator und eigenem step-Wert

const input = document.createElement('input');
input.type = 'number';
input.step = '5';
input.max = '40';
input.value = '10';

input.stepUp();      // 10 + 5
console.log(input.value);

input.stepUp(3);     // 15 + 3 * 5
console.log(input.value);

input.stepUp(10);    // würde 80 ergeben, wird auf max begrenzt
console.log(input.value);

15 30 40

Datumsfeld um eine Woche weiterschalten

// HTML: <input id="datum" type="date" value="2024-03-01">
const datum = document.querySelector('#datum');

// Ohne step-Attribut entspricht 1 Schritt einem Tag
datum.stepUp(7);
console.log(datum.value);

// Tastaturkürzel: Strg + Pfeil nach oben = +1 Monat bei type="month"
const monat = document.createElement('input');
monat.type = 'month';
monat.value = '2024-11';
monat.stepUp(2);
console.log(monat.value);

2024-03-08 2025-01

Fehler bei nicht unterstütztem Typ abfangen

const text = document.createElement('input');
text.type = 'text';

try {
  text.stepUp();
} catch (err) {
  console.log(err.name);
}

InvalidStateError

// Wichtig · Fallstricke

Keine Ereignisse: stepUp() löst weder input noch change aus. Framework-Bindungen (React, Vue usw.) und eigene Listener bekommen die Änderung nur mit, wenn du die Ereignisse selbst per dispatchEvent() auslöst.
InvalidStateError (DOMException): Diese Ausnahme wird geworfen, wenn der Typ nicht unterstützt wird (z. B. text) oder wenn step="any" gesetzt ist.
Liegt der aktuelle Wert schon über max, ändert stepUp() nichts. Es gibt keinen Fehler und keinen Umlauf auf min.
Nicht ganzzahlige Werte für stepIncrement werden nicht zuverlässig in allen Browsern gleich behandelt. Nutze am besten ganze Zahlen.
Die Methode funktioniert auch bei disabled- oder readonly-Feldern. Wenn der Nutzer das Feld nicht ändern darf, musst du das selbst prüfen.
Kompatibilität: in allen modernen Browsern verfügbar. Zu Datums- und Zeittypen gab es in älteren Safari-Versionen nur eingeschränkte Unterstützung.

Siehe auch

HTMLInputElement.stepDown() HTMLInputElement.step HTMLInputElement.valueAsNumber HTMLInputElement.valueAsDate HTMLInputElement EventTarget.dispatchEvent() HTMLSelectElement.item()