This is an unpublished editor’s draft that might include content that is not finalized. View the published version

Skip to content

Technique SCR41:Guarding keyboard event handlers against IME composition

About this Technique

This technique relates to:

This technique applies to web pages that use JavaScript keydown or keyup event handlers to trigger actions on interactive elements.

Description

The objective of this technique is to ensure that keydown and keyup event handlers do not unintentionally trigger application actions during Input Method Editor (IME) composition.

An IME allows users to enter characters not directly available on their keyboard, such as Chinese, Japanese, and Korean characters. During composition, keys like Enter, Tab, and Escape are used to control the IME (for example, confirming a candidate character), but they also fire keydown events on the page. If an event handler does not account for this, it may incorrectly execute application actions — such as submitting a form — while the user is still composing. This can violate SC 2.1.1 (keyboard shortcuts collide with IME controls) and SC 3.2.2 (unexpected change of context from input intended solely for the IME).

The KeyboardEvent.isComposing property is true during IME composition. Checking this property at the start of a handler lets developers skip application logic while the user is composing. Some older versions of Safari have a bug where isComposing is false on the final confirmation keypress; additionally checking event.keyCode === 229 provides a reliable cross-browser guard.

Alternatively, for form submission specifically, using the submit event is inherently IME-safe because the browser only fires it after composition is complete.

Examples

Example 1: Guarding a keydown handler with isComposing

In this example, a keydown event listener is attached to a text input. The handler checks event.isComposing and the Safari-compatibility fallback event.keyCode === 229 before triggering form submission when Enter is pressed. This ensures that pressing Enter to confirm an IME candidate does not accidentally submit the form.

const inputElement = document.querySelector("input");

inputElement.addEventListener("keydown", (event) => {
  if (event.isComposing || event.keyCode === 229) return;
  if (event.key === "Enter") submit();
});

Example 2: Using the submit event instead of keydown

The submit event on a form element is inherently IME-safe. The browser fires submit only after IME composition has ended, so this approach avoids the issue entirely for form submission scenarios.

const formElement = document.querySelector("form");

formElement.addEventListener("submit", (event) => {
  event.preventDefault();
  submit();
});

Related Resources

No endorsement implied.

Tests

Procedure

For each keydown or keyup event handler that executes an action when a specific key (such as Enter, Tab, or Escape) is pressed on an input element:

  1. Enable an IME for a language that requires composition (for example, Japanese, Chinese, or Korean).
  2. Focus the input element.
  3. Begin IME composition by typing a sequence that produces candidate characters.
  4. While IME composition is active, press Enter (or the key targeted by the handler) to confirm an IME candidate.
  5. Check that the application-level action (for example, form submission) was not triggered.
  6. End the IME session and press the same key again without an active IME composition.
  7. Check that the application-level action is triggered.

Expected Results

  • Checks #5 and #7 are true.
Back to Top