WheelEvent.momentum

Syntax

// W3C Pointer Events (Editor's Draft) — WheelEvent (normative IDL)
readonly attribute boolean momentum;

// WheelEventInit dictionary (normative IDL)
dictionary WheelEventInit : MouseEventInit {
  // ... deltaX, deltaY, deltaZ, deltaMode ...
  boolean momentum = false;
};

// Read it on any wheel event:
const isInertia = event.momentum;

Chromium's bindings: [RuntimeEnabled=WheelEventMomentum] readonly attribute boolean momentum; in wheel_event.idl, and [RuntimeEnabled=WheelEventMomentum] boolean momentum = false; in wheel_event_init.idl.

Inputs

The attribute is read-only — it takes no inputs; the platform sets it when it synthesizes the event (in Chromium, from the native event's momentum_phase != kPhaseNone). The dictionary member is the constructor input: new WheelEvent("wheel", { momentum: true }) sets the attribute's value on a script-created event — an authored echo, which proves nothing about platform behavior. To distinguish authored from native events, use event.isTrusted: script-constructed events are untrusted regardless of what their momentum reads. Omitted, the member defaults to false; the spec also requires the un-initialized value of the attribute to be false.

Outputs

A boolean. true means: this event was synthesized by the platform to simulate scroll inertia after the user ended the physical scroll interaction (the spec's example: the finger has lifted from the trackpad after a fling). false means otherwise — the spec's exact word. It covers a physical wheel or trackpad interaction still in progress, a script-constructed event (whose init defaults to false), and every event on platforms that don't emit momentum phases; it does not, by itself, establish physical input.

Errors

No exceptions and no error modes for reading the attribute: it always has a boolean value (un-initialized is false). The main trap is semantic, not exceptional: false does not prove a physical interaction on engines that don't implement the attribute — feature-detect ("momentum" in WheelEvent.prototype) before branching on it, and treat an absent attribute as “unknown”, not as “physical”. And since an authored event can echo true, true alone does not prove platform inertia either — pair it with isTrusted when that distinction matters.

Context

Receiver: any WheelEvent dispatched to the page — the interface inherits MouseEvent → UIEvent → Event, and the attribute is on WheelEvent.prototype (also readable on script-constructed instances).

Exposure: window and worker-independent — wheel events are a document/input concept; there is no permission, gesture, or secure-context requirement.

Availability: Chrome 151 per the milestone listing (desktop and Android per the feature detail); runtime feature WheelEventMomentum (status stable at trunk). Runtime qualification: Chromium maps the value from momentum_phase != kPhaseNone (unit-tested by injecting kPhaseBegan /kPhaseChanged /kPhaseNone in wheel_event_test.cc), and the implementing CL 7869775 records that Linux manual testing did not surface the value — real hardware/OS coverage needs Chrome 151+ hardware evidence.

Lifecycle

The value is fixed when the event is created (by the platform for native events, by the init dictionary for script events) and never changes for the event's lifetime. Within one trackpad fling the expected sequence is: physical wheel events (momentum === false) while the finger moves, then platform-synthesized inertia events (momentum === true) after it lifts, until inertia decays. There is no event that flips the value mid-stream, and no separate “momentum ended” signal — the true-valued events simply stop. Whether a given OS/device actually emits momentum phases is platform-dependent (Chromium's own Linux manual test did not surface them); verify on your target hardware.

Examples

// Split handling: react to physical input, let inertia glide natively.
container.addEventListener("wheel", (event) => {
  if (event.momentum) {
    // Platform inertia after the fling — leave native scrolling alone.
    return;
  }
  // Physical interaction: apply custom behavior.
  event.preventDefault();
  container.scrollLeft += event.deltaX;
}, { passive: false });

// Constructing one explicitly (defaults to false if omitted):
const synthetic = new WheelEvent("wheel", { deltaY: 120, momentum: false });

WheelEventInit.momentum

The dictionary member mirrors the attribute for constructor use: boolean momentum = false in WheelEventInit (a dictionary field, in WebIDL terms). Three exact semantics from WebIDL, because constructor behavior is where the traps live:

• Boolean conversion: the value converts via WebIDL's boolean conversion — any JavaScript value is accepted and ToBoolean'd, so the string "false" is truthy and produces momentum === true. Only genuine falsy values (false, 0, "", null, undefined, NaN) yield false.
• Default and undefined: omitted entirely — or passed explicitly as undefined — the member takes its declared default false (WebIDL applies the default whenever the value is undefined); existing new WheelEvent(...) call sites keep their meaning.
• Unknown members: per WebIDL dictionary semantics, members the dictionary doesn't declare are ignored — a typo'd key silently does nothing.

None of this is runtime proof of native behavior: a constructor round-trip only shows the dictionary was accepted and echoed. The spec notes the dictionary definitions are partly redundant with the attribute definitions (tracked as pointerevents#646).

WheelEventInit.momentum — outputs

The constructed event's momentum attribute reads back the converted value: ToBoolean of whatever the member held, or false when omitted. In Chromium this is a direct field copy from the initializer (is_momentum_(initializer->momentum()) in wheel_event.cc) — an echo of the authored value, independent of any platform event.

WheelEventInit.momentum — errors

WebIDL boolean conversion of an ordinary value never throws. But retrieving the member from the input object is a property access: if the source object defines a throwing getter for momentum, or is a Proxy with a throwing get trap, that exception propagates out of the constructor before any conversion runs. With ordinary data values, the failure modes are silent semantic ones: passing the string "false" produces true (truthy), and a misspelled member name is dropped without a signal. Neither says anything about platform inertia.

WheelEventInit.momentum — security and privacy

Because an authored event can carry momentum: true, the attribute value alone is not evidence of platform input — the distinguishing signal is event.isTrusted (false for every script-constructed event). Defensive handlers that branch on momentum should check isTrusted first when they care about physical-vs-scripted input. The member adds no storage, permission, or cross-origin channel; the parent feature's privacy review is still Pending, so broader assessments are open.

Compatibility

Vendor signals per the ChromeStatus API feature record; no behavioral WPT test for momentum as of 2026-07-26: the pinned tree at commit 1985b47 contains exactly two momentum declarations — the WebIDL surface itself in interfaces/pointerevents.idl (lines 90 and 98) — and no behavioral .html/.js test was found; no separately tracked web-feature on webstatus.dev (momentum query returns zero entries).

Security and privacy

The attribute reveals one bit about the user's input hardware behavior — whether the platform is currently synthesizing inertia — which is close to information the event stream itself already exposes (inertia events are observable as continued deltas). The ChromeStatus entry's privacy review is Pending as of 2026-07-26 (security review: Not applicable; the TAG review note says the feature is too small and non-controversial to justify one), so fingerprinting impact is not yet formally assessed — treat the one-bit disclosure as unreviewed rather than harmless. Authored events can echo momentum: true (see the dictionary member), so the attribute alone never proves native input.