# @webref/events

> Events of the Web platform and associated Web IDL interfaces

Latest version **1.25.1** (published 2026-09-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @webref/events
pnpm add @webref/events
yarn add @webref/events
bun add @webref/events
```

## Health

**Score 60/100 (C)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.25.1 |
| Published | 2026-09-04 |
| First published | 2022-08-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 187.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 468 |
| Maintainers | tidoust, dontcallmedom, foolip |

## Links

- npm: https://www.npmjs.com/package/@webref/events
- Repository: https://github.com/w3c/webref
- Homepage: https://github.com/w3c/webref#readme
- Issues: https://github.com/w3c/webref/issues
- npm.io page: https://npm.io/package/@webref/events

## Recent versions

- 1.25.1 (latest) — 2026-09-04
- 1.25.0 — 2026-08-26
- 1.24.2 — 2026-06-19
- 1.24.1 — 2026-06-10
- 1.24.0 — 2026-05-27
- 1.23.0 — 2026-05-06
- 1.22.1 — 2026-03-25
- 1.22.0 — 2026-03-05
- 1.21.0 — 2026-02-25
- 1.20.2 — 2026-02-10
- 1.20.1 — 2026-01-28
- 1.20.0 — 2026-01-14
- 1.19.3 — 2026-01-05
- 1.19.2 — 2025-11-27
- 1.19.1 — 2025-10-15
- … 43 more at https://npm.io/package/@webref/events/versions

## README

# Events of the Web platform and associated Web IDL interfaces

This package contains a consolidated list of events defined across specs, scraped from the latest versions of web platform specifications in [webref](https://github.com/w3c/webref), along with the name of the Web IDL interfaces that these events use and target. Fixes are applied to ensure that [guarantees](#guarantees) hold.


# API

The async `listAll()` method resolves with a list of events. Example:

```js
const events = require('@webref/events');

events.listAll().then(all => {
  for (const event of all) {
    // do something with the json object that describes the event
  }
});
```

Each event is described by an object with the following properties:
- `type`: contains the name of the event
- `interface`: describes the IDL interface used by the event
- `targets`: lists the target interfaces on which the event may fire. Each target in the list is an object with a `target` property that gives the interface name, a `bubbles` property only set when the interface belongs to a bubbling tree to assert whether the event bubbles, and a `bubblingPath` property only when the event effectively bubbles and that lists the core interfaces on which the event can theoretically bubble.
- optionally, an `href` property that is a URL to the event definition in a spec
- optionally, an `src` property that describes where the extraction first detected that the event is fired in the spec

The following example illustrates access to main properties:

```js
const events = require('@webref/events');

events.listAll().then(all => {
  for (const event of all) {
    console.log();
    console.log(`Event type=${event.type}
      interface=${event.interface}
      targets=${event.targets
        .map(t => t.target +
          (t.bubbles === undefined ? '' : ` (bubbles: ${t.bubbles})`))
        .join(', ')}`);
  }
});
```

Actual interfaces on which an event will bubble may be interfaces that inherit from the interfaces listed in `bubblingPath`. For instance, for a bubbling event that fires on `HTMLSelectElement`, the bubbling path will be `["Node", "Document", "Window"]`, even though the event will only bubble on `HTMLElement` and not on all types of `Node` in practice.


# Guarantees

The following guarantees are provided by this package:
- All events have a `type` attribute that match the name of the event
- All events have a `interface` attribute to describe the interface used by the Event. The Web IDL interface exists in the latest version of the [`@webref/idl` package](https://www.npmjs.com/package/@webref/idl) at the time the `@webref/events` package is released, and represents an actual interface (i.e. not a mixin).
- All events have a `targets` attribute with a non-empty list of target interfaces on which the event may fire. All Web IDL interfaces in the list exist in the latest version of the [`@webref/idl` package](https://www.npmjs.com/package/@webref/idl) at the time the `@webref/events` package is released, and represent an actual interface (i.e. not a mixin).
- The `bubbles` attribute is always set to a boolean value for target interfaces that belong to a bubbling tree (DOM, IndexedDB, Serial API, Web Bluetooth).
- The `bubbles` attribute is only set for target interfaces that belong to a bubbling tree.
- The `bubblingPath` attribute is only set for target interfaces on which the event bubbles.
- The `targets` attribute contains the top most interfaces in an inheritance chain, unless bubbling conditions differ. For instance, the list may contain `{ "target": "Element", "bubbles": true }` but not also `{ "target": "HTMLElement", "bubbles": true }` since `HTMLElement` inherits from `Element`.
- For target interfaces that belong to a bubbling tree, the `targets` attribute only contains the deepest interface in the bubbling tree on which the event may fire and bubble. For instance, the list may contain `{ "target": "HTMLElement", "bubbles": true }`, but not also `{ "target": "Document" }` since event would de facto fire at `Document` through bubbling.

---
_Source: https://npm.io/package/@webref/events · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._