Miss any of our Open RFC calls?Watch the recordings here! »


4.0.5 • Public • Published

o-viewport MIT licensed

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


Check out how to include 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



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.

import oViewport from './../main.js';
// Fire for orientation events.
// 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 for more examples.


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.

// Stop listening to the orientation event.


Provides a reasonably reliable way (more so than window.orientation) of obtaining the current orientation of the viewport.

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


Provides a reasonably reliable way of obtaining the current visibility of the viewport.

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


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.

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


Provides a reliable way of obtaining the current scroll position of the viewport. returns an object with the properties width, height, left and top

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:

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

The default value for each of these is 100ms


Turns on debug mode (logging event details to the console).


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:

import oViewport from './../main.js';
// Fire for all viewport events.
// 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.


  • No additional properties.


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


  • data.hidden: true or false


  • 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


  • 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 method to customise throttling.


State Major Version Last Minor Release Migration guide
✨ active 4 N/A migrate to v4
⚠ maintained 3 3.3 migrate to v3
╳ deprecated 2 2.3 migrate to v2
╳ deprecated 1 1.5 N/A


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

This software is published under the MIT licence.


npm i @financial-times/o-viewport

DownloadsWeekly Downloads






Unpacked Size

19.8 kB

Total Files


Last publish


  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar
  • avatar