KeyboardEvent.getModifierState()

There was a scripting error on this page. While it is being addressed by site editors, you can view partial content below.

{{ APIRef }}

The KeyboardEvent.getModifierState() method returns the current state of the specified modifier key, true if the modifier is active (that is the modifier key is pressed or locked), otherwise, false.

Syntax

active = event.getModifierState(keyArg);
keyArg
A modifier key value. The value must be one of the KeyboardEvent.key values which represent modifier keys or "Accel". This is case-sensitive.

Modifier keys on Internet Explorer

IE9 uses "Scroll" for "ScrollLock" and "Win" for "OS".

Modifier keys on Gecko

When getModifierState() returns true on Gecko?
  Windows Linux (GTK) Mac Android 2.3 Android 3.0 or latter
"Alt" Either Alt key or AltGr key pressed Alt key pressed option key pressed Alt key or option key pressed
"AltGraph"

Both Alt and Ctrl keys are pressed, or AltGr key is pressed

Level 3 Shift key (or Level 5 Shift key ) pressed option key pressed Not supported
"CapsLock" During LED for Caps Lock turned on Not supported While CapsLock is locked
"Control" Either Ctrl key or AltGr key pressed Ctrl key pressed control key pressed menu key pressed. Ctrl key, control key or menu key pressed.
"Fn" Not supported Function key is pressed, but we're not sure what key makes the modifier state active. Fn key on Mac keyboard doesn't cause this active.
"FnLock" Not supported
"Hyper" Not supported
"Meta" Not supported Meta key pressed command key pressed Not supported Windows Logo key or command key pressed
"NumLock" During LED for Num Lock turned on A key on numpad pressed Not supported While NumLock is locked
"OS" Windows Logo key pressed Super key or Hyper key pressed (typically, mapped to Windows Logo key) Not supported
"ScrollLock" During LED for Scroll Lock turned on During LED for Scroll Lock turned on, but typically this isn't supported by platform Not supported While ScrollLock is locked
"Shift" Shift key pressed
"Super" Not supported
"Symbol" Not supported
"SymbolLock" Not supported
  • On the other platforms, "Alt", "Control" and "Shift" may be supported.
  • All modifiers (except "FnLock", "Hyper", "Super" and "Symbol" which are defined after Gecko implements this) are always supported for untrusted events on Gecko. This doesn't depend on the platform.

"Accel" virtual modifier

"Accel" virtual modifier is useful in some cases. event.getModifierState("Accel") returns true when a modifier which is the typical modifier key for the shortcut key is pressed.

For example, on Windows, pressing Ctrl key may make it return true. However, on Mac, pressing command key may make it return true.

Note that which modifier key makes it return true depends on platforms, browsers and user settings. For example, Firefox users can customize this with a pref, "ui.key.accelKey".

In other words, when web applications want to implement custom shortcut keys, this is useful, although they might conflict with brower's shortcut keys.

Example

// Ignore if following modifier is active.
if (event.getModifierState("Fn") ||
    event.getModifierState("Hyper") ||
    event.getModifierState("OS") ||
    event.getModifierState("Super") ||
    event.getModifierState("Win") /* hack for IE */) {
  return;
}

// Also ignore if two or more modifiers except Shift are active.
if (event.getModifierState("Control") +
    event.getModifierState("Alt") +
    event.getModifierState("Meta") > 1) {
  return;
}

// Handle shortcut key with standard modifier
if (event.getModifierState("Accel")) {
  switch (event.key.toLowerCase()) {
    case "c":
      if (event.getModifierState("Shift")) {
        // Handle Accel + Shift + C
        event.preventDefault(); // consume the key event
      }
      break;
    case "k":
      if (!event.getModifierState("Shift")) {
        // Handle Accel + K
        event.preventDefault(); // consume the key event
      }
      break;
  }
  return;
}

// Do somethig different for arrow keys if ScrollLock is locked.
if ((event.getModifierState("ScrollLock") ||
       event.getModifierState("Scroll") /* hack for IE */) &&
    !event.getModifierState("Control") &&
    !event.getModifierState("Alt") &&
    !event.getModifierState("Meta")) {
  switch (event.key) {
    case "ArrowDown":
    case "Down": // hack for IE and old Gecko
      event.preventDefault(); // consume the key event
      break;
    case "ArrowLeft":
    case "Left": // hack for IE and old Gecko
      // Do something different if ScrollLock is locked.
      event.preventDefault(); // consume the key event
      break;
    case "ArrowRight":
    case "Right": // hack for IE and old Gecko
      // Do something different if ScrollLock is locked.
      event.preventDefault(); // consume the key event
      break;
    case "ArrowUp":
    case "Up": // hack for IE and old Gecko
      // Do something different if ScrollLock is locked.
      event.preventDefault(); // consume the key event
      break;
  }
}

Although, this example uses .getModifierState() with "Alt", "Control", "Meta" and "Shift", perhaps it's better for you to use altKey, ctrlKey, metaKey and shiftKey because they are shorter and may be faster.

Specifications

Specification Status Comment
Document Object Model (DOM) Level 3 Events Specification
The definition of 'KeyboardEvent.getModifiedState' in that specification.
Working Draft Initial definition (Modifier Keys spec)

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support Not supported 15.0 (15.0) 9.0 Not supported Not supported
"Accel" support Not supported 32.0 (32.0) Not supported Not supported Not supported
Feature Android Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile
Basic support ? 15.0 (15.0) ? ? ?
"Accel" support ? 32.0 (32.0) ? ? ?

See also

Document Tags and Contributors

Contributors to this page: ngbrown, fscholz, teoli, kscarfone, Masayuki
Last updated by: ngbrown,