# @financial-times/o-viewport

> Utility for attaching debounced listeners to resize, scroll, orientation and visibility events on window

Latest version **5.1.2** (published 2023-10-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install @financial-times/o-viewport
pnpm add @financial-times/o-viewport
yarn add @financial-times/o-viewport
bun add @financial-times/o-viewport
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.1.2 |
| Published | 2023-10-27 |
| First published | 2019-02-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 18.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | robertboulton, seraph2000, hamza.samih, notlee, emmalewis, aendra, the-ft, rowanmanning, chee, alexwilson |
| Keywords | debounce, listen, event |

## Links

- npm: https://www.npmjs.com/package/@financial-times/o-viewport
- Homepage: https://registry.origami.ft.com/components/o-viewport
- Issues: https://github.com/Financial-Times/origami/issues/new?labels=o-viewport,components
- npm.io page: https://npm.io/package/@financial-times/o-viewport

## Alternatives

- [async-exit-hook](https://npm.io/package/async-exit-hook.md) — 3.7M weekly downloads
- [evnty](https://npm.io/package/evnty.md) — 7.2K weekly downloads
- [eleventy-plugin-asciidoc](https://npm.io/package/eleventy-plugin-asciidoc.md) — 3.5K weekly downloads
- [@jswork/next-get2get](https://npm.io/package/@jswork/next-get2get.md) — 945 weekly downloads
- [@dashersw/axon](https://npm.io/package/@dashersw/axon.md) — 934 weekly downloads

## Recent versions

- 5.1.2 (latest) — 2023-10-27
- 5.0.0-beta.0 (prerelease) — 2021-04-29
- 5.1.1 — 2022-01-13
- 5.1.0 — 2021-11-24
- 5.0.1 — 2021-09-21
- 5.0.0 — 2021-06-21
- 5.0.0-0 — 2021-04-22
- 4.0.5 — 2020-09-07
- 4.0.4 — 2020-08-07
- 4.0.3 — 2020-05-06
- 4.0.2 — 2020-04-09
- 4.0.1 — 2020-03-24
- 4.0.0 — 2019-11-21
- 4.0.0-beta.1 — 2019-11-13
- 3.3.3 — 2019-05-13
- … 4 more at https://npm.io/package/@financial-times/o-viewport/versions

## README

# o-viewport [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](#licence)

Utility for attaching debounced listeners to resize, scroll, orientation and visibility events on `window`.

## Usage

Check out [how to include Origami components in your project](https://origami.ft.com/documentation/components/#including-origami-components-in-your-project) to get started with `o-viewport`.

_Note: within the component's API and in the documentation below `orientation` and `visibility` are used instead of `orientationchange` or `visibilitychange`, but the actual browser event listened to is `orientationchange` or `visibilitychange`_

## Methods

### `o-viewport#listenTo(eventType)`
Attaches a debounced/throttled (as appropriate) listener to events on window \[`resize`, `scroll`, `orientation`, `visibility` or `all`\] which in turn fires events within the `oViewport` namespace (see **Events** below).

_Note: all will enable all o-viewport events._

```js
import oViewport from '@financial-times/o-viewport';

// Fire for orientation events.
oViewport.listenTo('orientation');

// Listener for debounced orientation events via o-viewport.
document.body.addEventListener('oViewport.orientation', function(event) {
	console.log(event.type); // oViewport.orientation
	console.log(event.viewport); // { height, width }
	console.log(event.orientation); // 'portrait' or 'landscape'
	console.log(event.originalEvent); // the original browser event
});
```

See [events](#events) for more examples.

### `o-viewport#stopListeningTo(eventType)`
Remove the attached listener from the window for the named event \[`resize`, `scroll`, `orientation`, `visibility` or `all`\].

_Note: all will disable all o-viewport events._

```js
// Stop listening to the orientation event.
oViewport.stopListeningTo('orientation');
```

### `o-viewport#getOrientation()`
Provides a reasonably reliable way (more so than `window.orientation`) of obtaining the current orientation of the viewport.

```js
oViewport.getOrientation(); // 'portrait' or 'landscape'
```

### `o-viewport#getVisibility()`
Provides a reasonably reliable way of obtaining the current visibility of the viewport.

```js
oViewport.getVisibility(); // boolean, true if visible
```

### `o-viewport#getSize(ignoreScrollbars)`
Provides a reliable way of obtaining the current dimensions of the browser window. Returns an object with the properties `width` and `height`.

By default or if no parameters are passed the method will return the size of the viewport inclusive of the scrollbars. However in certain cases (e.g. adverts) you may want to get the size of the viewport without the scroll bars. In such case pass `true` to the method in order to ignore the scrollbars.

```js
oViewport.getSize(); // {width: 108, height: 100} including scrollbar width
oViewport.getSize(true); // {width: 100, height: 100} without scrollbars
```

### `o-viewport#getScrollPosition()`
Provides a reliable way of obtaining the current scroll position of the viewport. returns an object with the properties `width`, `height`, `left` and `top`

```js
oViewport.getScrollPosition(); // {width: 100, height: 100, left: 0, top: 10}
```

### `o-viewport#setThrottleInterval(eventType, interval)` _Product use only_
Sets the debounce/throttle interval for a given event \[`scroll`, `resize` or `orientation`\].
As a shorthand, calling `setThrottleInterval` with 1 - 3 numbers will set the intervals for `scroll`, `resize` and `orientation` in that order e.g. `setThrottleInterval(100, undefined, 300)` is equivalent to:

```js
setThrottleInterval('scroll', 100)
setThrottleInterval('resize') // which does nothing
setThrottleInterval('orientation', 300)
setThrottleInterval('visibility', 30)
```

The default value for each of these is 100ms

### `o-viewport#debug()`
Turns on debug mode (logging event details to the console).

## Events
Each of these custom events are fired on `document.body`. For each custom event `event.detail.originalEvent` contains a reference to the original browser event and `event.detail.viewport` the result of `o-viewport#getSize()`. For example:

```js
import oViewport from '@financial-times/o-viewport';

// Fire for all viewport events.
oViewport.listenTo('all');

// Listener for debounced visibility events via o-viewport.
document.body.addEventListener('oViewport.visibility', function(event) {
	console.log(event.type); // oViewport.resize
	console.log(event.detail.viewport); // { height, width }
	console.log(event.detail.hidden); // boolean
});
```

Note `event.detail.hidden` is unique to the `oViewport.visibility` event. Additional unique properties for `o-viewport` events are detailed below.

### `oViewport.resize`

-   No additional properties.

### `oViewport.orientation`

-   data.orientation: 'portrait' or 'landscape'

### `oViewport.visibility`

-   data.hidden: true or false

### `oViewport.scroll`

-   data.scrollLeft: unitless px value of scroll position
-   data.scrollTop: unitless px value of scroll position
-   data.scrollHeight: unitless px value of scroll height
-   data.scrollWidth: unitless px value of scroll width

## Throttling

-   `oViewport.resize`, `oViewport.orientation` and  `oViewport.visibility` are debounced i.e. if the native event fires several times in quick succession the custom event will fire only once `n` milliseconds after the last event, where `n` is the throttle interval
-   `oViewport.scroll` is throttled i.e. if the native `scroll` event fires several times in quick succession the custom event will fire at most once every `n` milliseconds, where `n` is the throttle interval

Use the [setThrottleInterval](#o-viewportsetthrottleintervaleventtype-interval-product-use-only) method to customise throttling.

## Migration

State | Major Version | Last Minor Release | Migration guide |
:---: | :---: | :---: | :---:
✨ active | 5 | N/A | [migrate to v5](MIGRATION.md#migrating-from-v4-to-v5) |
⚠ maintained | 4 | 4.0.5 | [migrate to v4](MIGRATION.md#migrating-from-v3-to-v4) |
╳ deprecated | 3 | 3.3 | [migrate to v3](MIGRATION.md#migrating-from-v2-to-v3) |
╳ deprecated | 2 | 2.3 | [migrate to v2](MIGRATION.md#migrating-from-v1-to-v2) |
╳ deprecated | 1 | 1.5 | N/A |

***

## Licence

Copyright (c) 2016 Financial Times Ltd. All rights reserved.

This software is published under the [MIT licence](http://opensource.org/licenses/MIT).

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