# @adoratorio/hermes

> A JS utility for scroll events normalization and management

Latest version **2.0.0** (published 2026-09-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @adoratorio/hermes
pnpm add @adoratorio/hermes
yarn add @adoratorio/hermes
bun add @adoratorio/hermes
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-09-07 |
| First published | 2019-03-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 72.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Adoratorio Studio |
| Maintainers | adoratorio.studio, danieleborra, ne-u, andrea_ |
| Keywords | events, js, scroll, hermes, adoratorio |

## Links

- npm: https://www.npmjs.com/package/@adoratorio/hermes
- Repository: https://github.com/Adoratorio/hermes
- Homepage: https://github.com/Adoratorio/hermes#readme
- Issues: https://github.com/Adoratorio/hermes/issues
- npm.io page: https://npm.io/package/@adoratorio/hermes

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 2.0.0 (latest) — 2026-09-07
- 1.0.4 — 2026-07-15
- 1.0.3 — 2025-10-24
- 1.0.2 — 2025-05-28
- 1.0.1 — 2023-11-07
- 1.0.0 — 2022-11-14
- 0.1.35 — 2022-08-01
- 0.1.34 — 2020-08-25
- 0.1.33 — 2020-08-25
- 0.1.32 — 2020-08-24
- 0.1.31 — 2020-08-24
- 0.1.30 — 2020-07-10
- 0.1.29 — 2020-02-24
- 0.1.27 — 2019-06-20
- 0.1.26 — 2019-06-20
- … 29 more at https://npm.io/package/@adoratorio/hermes/versions

## README

# Hermes

A utility library for scroll, wheel, keyboard, and touch event normalization.

## Installation

```bash
npm install @adoratorio/hermes
```

## Usage

This package is ESM-only. Import it as a module:

```typescript
import Hermes from '@adoratorio/hermes';

const hermes = new Hermes({
  mode: Hermes.MODE.VIRTUAL,
  events: [Hermes.EVENTS.WHEEL, Hermes.EVENTS.TOUCH]
});

hermes.on((event) => {
  console.log(event.type, event.delta);
});
```

## Configuration

| Parameter | Type | Default | Description |
| :-------- | :--: | :-----: | :---------- |
| `mode` | `string` | `Hermes.MODE.VIRTUAL` | `VIRTUAL` uses wheel/touch/key events; `NATIVE` listens to native scroll. |
| `events` | `Array<string>` | `[WHEEL, TOUCH, KEYS]` | The events to listen to. |
| `root` | `HTMLElement \| Window`| fallback | The DOM element used as the event listener root. |
| `passive` | `boolean` | `true` | Use passive event listeners (improves perf, but prevents `preventDefault()`). |
| `emitGlobal` | `boolean` | `false` | Emit global custom events on the `window`. |
| `touchMultiplier` | `number` | `2` | Multiplier for touch values. |
| `keyMultiplier` | `number \| KeyMultipliers` | `1` | Multiplier applied to keyboard-scroll deltas, globally or per key (keyed by `Hermes.KEY`). |
| `debug` | `boolean` | `false` | Enable namespaced `console.warn` diagnostics for recoverable issues (contract violations always throw). |

### Events option

* `Hermes.EVENTS.WHEEL` - wheel events, normalized across `deltaMode`s.
* `Hermes.EVENTS.TOUCH` - touch moves; the release emits one more `touch` event whose delta is the gesture momentum.
* `Hermes.EVENTS.KEYS` - every scroll key: arrows, space (shift+space scrolls up), page up/down, home/end.
* `Hermes.EVENTS.SPACEBAR` / `Hermes.EVENTS.ARROWS` - narrower key groups, used only when `KEYS` is not enabled.

Keys are matched on `KeyboardEvent.key`; the values are exposed as `Hermes.KEY` (`ArrowUp`, `PageDown`, `Home`, ...). Keys pressed inside inputs, textareas, selects and contenteditable elements are ignored.

## Methods

```typescript
// Sets (or replaces) the handler and binds the listeners on the first call
hermes.on(handler: HermesHandler);

// Clears the handler and unbinds listeners
hermes.off();

// Alias for off()
hermes.destroy();

// Getter/Setter that gates emission on/off without unbinding
hermes.listen = false;

// Whether the listeners are currently bound
hermes.bound;

// Multipliers can be changed at runtime
hermes.touchMultiplier = 1.5;
hermes.keyMultiplier = { [Hermes.KEY.SPACE]: 0.5 };
```

## Events

The handler receives a `HermesEvent` object:

```typescript
interface HermesEvent {
  type: string;          // e.g., 'wheel', 'touch', 'keys'
  delta: Vec2;           // Normalized delta
  originalEvent: Event;  // The underlying DOM event
}
```

## TypeScript Support

Hermes is entirely written in TypeScript and exports specific types like `HermesEvent`, `HermesOptions`, `KeyMultipliers`, and the `MODE`, `EVENTS`, `KEY` and `DELTA_MODE` constants.

## Maintenance and compatibility

See [MAINTAINERS.md](MAINTAINERS.md), [CONTRIBUTING.md](CONTRIBUTING.md) and
[CHANGELOG.md](CHANGELOG.md). Historical contributor credits are retained.
The CI runtime is Node 24; DOM instances are client-only. Imports are SSR-safe.
The runtime expects native ES2023 support; TypeScript does not provide browser
polyfills. DOM functionality uses requestAnimationFrame, Pointer/Touch Events
and observers where applicable. Test the target browser matrix before release.

`pageSize: 'root'` opts in to root viewport dimensions for page-mode wheel
input, space and PageUp/PageDown. The default `pageSize: 'legacy'` preserves
existing wheel scaling and keyboard sensitivity.

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