ObserveViewport_connectViewport_useViewport.md

Observe the Viewport

Dependent on the use case we support different ways to connect to the viewport properties. All options described in this document will expose the current scroll and dimensions information collected by a ViewportProvider.

Render Props/ Event Handler: ObserveViewport

Render props are easy to implement in the most situations but the event handler allows more control about performance and to trigger side effects.

API

Property	Type	Required?	Description
onUpdate	function		Triggers as soon as a viewport update was detected. Contains the Viewport as the first argument and the last return of recalculateLayoutBeforeUpdate as the second argument
recalculateLayoutBeforeUpdate	function		Enables a way to calculate layout information for all components as a badge before the onUpdate call. Contains the Viewport as the first argument. See recalculateLayoutBeforeUpdate
children	function		Like onUpdate but expects to return that will be rendered on the page. Contains the Viewport as the first argument.
deferUpdateUntilIdle	boolean		Defers to trigger updates until the collector is idle. See Defer Events
priority	'low', 'normal', 'high', 'highest'		Allows to set a priority of the update. See Defer Events
disableScrollUpdates	boolean		Disables updates to scroll events
disableDimensionsUpdates	boolean		Disables updates to dimensions events

Example

import * as React from 'react';
import {
  ViewportProvider,
  ObserveViewport,
} from 'react-viewport-uitls';

const handleUpdate = ({ scroll, dimensions }) {
  console.log(scroll, dimensions);
}

render(
  <ViewportProvider>
    <div>
      <ObserveViewport priority="low" onUpdate={handleUpdate} />
    </div>
    <ObserveViewport disableDimensionsUpdates>
      {({ scroll }) => <div>{scroll.x}</div>}
    </ObserveViewport>
  </ViewportProvider>,
  document.querySelector('main')
);

HOC: connectViewport

This is just a wrapper for the ObserveViewport to implement the HOC pattern.

API

Property	Type	Required?	Description
omit	['scroll', 'dimensions']		Allows to disable scroll or dimensions events for the higher order component
deferUpdateUntilIdle	boolean		Defers to trigger updates until the collector is idle. See Defer Events.
options.priority	'low', 'normal', 'high', 'highest'		Allows to set a priority of the update. See Defer Events

Example

import * as React from 'react';
import {
  ViewportProvider,
  connectViewport,
} from 'react-viewport-utils';

const Component = ({ scroll, dimensions }) => (
  <>
    <div>Dimension (inner)width: ${dimensions.width}</div>
    <div>Dimension (inner)height: ${dimensions.height}</div>
    <div>Scroll X: {scroll.x}</div>
    <div>Scroll Y: {scroll.y}</div>
  </>
);
const ConnectedComponent = connectViewport()(Component);

render(
  <ViewportProvider>
    <div>
      <ConnectedComponent />
    </div>
  </ViewportProvider>,
  document.querySelector('main')
);

Hooks: useViewport, useScroll, useDimensions, useLayoutSnapshot

!!! Hooks require a ViewportProvider as a parent and only work with react v16.7.0 !!!

API

Argument	Type	Required?	Description
options.disableScrollUpdates	boolean		Disables updates to scroll events (only for useViewport and useLayoutSnapshot)
options.disableDimensionsUpdates	boolean		Disables updates to dimensions events (only for useViewport and useLayoutSnapshot)
options.deferUpdateUntilIdle	boolean		Defers to trigger updates until the collector is idle. See Defer Events
options.priority	'low', 'normal', 'high', 'highest'		Allows to set a priority of the update. See Defer Events

Hooks: useMutableViewport

!!! Hooks require a ViewportProvider as a parent and only work with react v16.7.0 !!!

Exposes the current viewport state as a mutable and readonly object. It will not trigger updates when the value on the viewport change but allows to access the current and most up to date information at any time without any negative performance impact.

Example

import * as React from 'react';
import { useScroll, useDimensions } from 'react-viewport-utils';

function Component() {
  const ref = React.useRef()
  const mutableViewport = useMutableViewport();
  useRectEffect((rect) => {
    console.log(
      'Is element above the current scroll position?',
      mutableViewport.scroll.y > rect.bottom
    )
  }, ref)

  return (
    <div ref={ref} />
  );
}

Hook Effects: useViewportEffect, useScrollEffect, useDimensionsEffect

Hook effects allow to trigger side effects on change without updating the component.

!!! Hooks require a ViewportProvider as a parent and only work with react v16.7.0 !!!

API

Argument	Type	Required?	Description
effect	(Viewport | Scroll | Dimensions) => void	x	Disables updates to scroll events (only for useViewport)
options.disableScrollUpdates	boolean		Disables updates to scroll events (only for useViewport)
options.disableDimensionsUpdates	boolean		Disables updates to dimensions events (only for useViewport)
options.deferUpdateUntilIdle	boolean		Defers to trigger updates until the collector is idle. See Defer Events
options.priority	'low', 'normal', 'high', 'highest'		Allows to set a priority of the update. See Defer Events
options.recalculateLayoutBeforeUpdate	function		Enables a way to calculate layout information for all components as a badge before the effect call. Contains Viewport, Scroll or Dimensions as the first argument, dependent of the used hook. See recalculateLayoutBeforeUpdate
deps	array		Array with dependencies. In case a value inside the array changes, this will force an update to the effect function

Example

import * as React from 'react';
import { useScrollEffect, useViewportEffect } from 'react-viewport-utils';

function Component() {
  const ref = React.useRef()
  useScrollEffect((scroll) => {
    console.log(scroll);
  });
  useViewportEffect((viewport, elementWidth) => {
    console.log(viewport, top);
  }, {
    recalculateLayoutBeforeUpdate: () => ref.current ? ref.current.getBoundingClientRect().width : null
  });

  return <div ref={ref} />;
}

Related docs

• ViewportProvider
• Types