MouseEvent.button — Eigenschaft · JavaScript-Referenz

Signatur

MouseEvent.button

Beschreibung

Die Eigenschaft button eines MouseEvent gibt eine Ganzzahl zurück. Sie sagt, welche einzelne Taste für das aktuelle Ereignis verantwortlich ist. Das ist nützlich, um Links-, Mittel- und Rechtsklicks zu unterscheiden, etwa für eigene Kontextmenüs, „In neuem Tab öffnen“ per Mittelklick oder die Navigation mit den Vor/Zurück-Tasten der Maus.

Die Werte sind:

0: Haupttaste, meist die linke (bei Einstellungen für Linkshänder die rechte)
1: Hilfstaste, meist die mittlere Taste bzw. das Mausrad
2: Sekundärtaste, meist die rechte
3: vierte Taste, meist „Zurück“ im Browser
4: fünfte Taste, meist „Vorwärts“ im Browser

Verlässliche Werte liefert button nur bei Ereignissen, die durch das Drücken oder Loslassen einer Taste entstehen: mousedown, mouseup, click, auxclick, dblclick und contextmenu. Bei mousemove, mouseover und ähnlichen Ereignissen steht der Wert in der Regel auf 0 und bedeutet dort nichts. Wer wissen will, welche Tasten gerade gedrückt gehalten werden, auch mehrere gleichzeitig, nimmt die Bitmaske MouseEvent.buttons.

Rückgabewert

Typ

number

Beschreibung

Eine Ganzzahl von 0 bis 4, die die auslösende Taste angibt. Bei Zeigerereignissen ohne Tastenänderung (z. B. pointermove) kann der Wert -1 sein.

Beispiele

Gedrückte Maustaste erkennen

const namen = ['Links (Haupttaste)', 'Mitte (Rad)', 'Rechts', 'Zurück', 'Vorwärts'];

document.addEventListener('mousedown', (event) => {
  const name = namen[event.button] ?? `Unbekannt (${event.button})`;
  console.log(`Gedrückt: ${name}`);
});

Gedrückt: Mitte (Rad)

Eigenes Kontextmenü per Rechtsklick

const flaeche = document.querySelector('#zeichenflaeche');
const menue = document.querySelector('#kontextmenue');

// Standard-Kontextmenü des Browsers unterdrücken
flaeche.addEventListener('contextmenu', (event) => event.preventDefault());

flaeche.addEventListener('mouseup', (event) => {
  if (event.button !== 2) return; // nur die rechte Taste
  menue.style.left = `${event.clientX}px`;
  menue.style.top = `${event.clientY}px`;
  menue.hidden = false;
});

document.addEventListener('mousedown', (event) => {
  if (event.button === 0 && !menue.contains(event.target)) {
    menue.hidden = true;
  }
});

Mittelklick und Maustasten für Zurück/Vorwärts in einer SPA

const liste = document.querySelector('#artikelliste');

// auxclick feuert für alle Tasten außer der Haupttaste
liste.addEventListener('auxclick', (event) => {
  const eintrag = event.target.closest('[data-url]');
  if (!eintrag || event.button !== 1) return;
  event.preventDefault();
  window.open(eintrag.dataset.url, '_blank', 'noopener');
});

// Zurück/Vorwärts-Tasten in der Single-Page-App abfangen
window.addEventListener('mouseup', (event) => {
  if (event.button === 3) {
    event.preventDefault();
    history.back();
  } else if (event.button === 4) {
    event.preventDefault();
    history.forward();
  }
});

Unterschied zwischen button und buttons

document.addEventListener('mousedown', (event) => {
  // button: die Taste, die dieses Ereignis ausgelöst hat
  // buttons: Bitmaske aller aktuell gedrückten Tasten (1=links, 2=rechts, 4=Mitte)
  console.log({ button: event.button, buttons: event.buttons });
});

// Links halten, dann zusätzlich rechts drücken:

{ button: 0, buttons: 1 } { button: 2, buttons: 3 }

// Wichtig · Fallstricke

Mehrdeutiger Wert 0: Bei mousemove, mouseenter usw. ist button meist 0, obwohl vielleicht gar keine Taste gedrückt ist. Für Drag-Logik daher event.buttons auswerten.
Andere Nummerierung: In button ist Mitte 1 und rechts 2. In der Bitmaske buttons ist dagegen rechts 2 und Mitte 4. Die beiden werden leicht verwechselt.
Linkshänder-Einstellung: 0 steht für die Haupttaste, nicht zwingend für die linke. Das Betriebssystem kann die Tasten tauschen.
click nur für die Haupttaste: Moderne Browser lösen click nur bei der Haupttaste aus. Für Mittel- und Rechtsklicks auxclick, mouseup oder contextmenu verwenden.
Tasten 3/4: Nicht jede Maus hat sie. Der Browser kann sie außerdem direkt für die Navigation nutzen, und preventDefault() verhindert das nicht in allen Browsern zuverlässig.
Altlast: Der alte Internet Explorer (vor IE9) verwendete eine eigene Bitmasken-Semantik (1=links, 4=Mitte). Heute spielt das keine Rolle mehr. Die Eigenschaft wird in allen modernen Browsern unterstützt.
Zeigerereignisse: PointerEvent erbt button. Bei pointermove ohne Tastenänderung ist der Wert -1.
Touch/Stift: Berührungen und Stiftkontakte werden meist als 0 gemeldet. Die Stift-Radiertaste kann 5 liefern.

Siehe auch

MouseEvent MouseEvent.buttons PointerEvent MouseEvent.altKey MouseEvent.layerX