Viewport

Viewport is a module for responding to changes in the browser viewport size. It registers its own data module, updated in response to browser media queries on a standard set of supported breakpoints. This data and the included higher-order components can be used in your own modules and components to implement viewport-dependent behaviors.

Installation

Install the module

npm install @wordpress/viewport --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

The standard set of breakpoint thresholds is as follows:

Name	Pixel Width
huge	1440
wide	1280
large	960
medium	782
small	600
mobile	480

Data Module

The Viewport module registers itself under the core/viewport data namespace and is exposed from the package as store.

import { select } from '@wordpress/data';
import { store } from '@wordpress/viewport';

const isSmall = select( store ).isViewportMatch( '< medium' );

The isViewportMatch selector accepts a single string argument query. It consists of an optional operator and breakpoint name, separated with a space. The operator can be < or >=, defaulting to >=.

import { select } from '@wordpress/data';
import { store } from '@wordpress/viewport';

const { isViewportMatch } = select( store );
const isSmall = isViewportMatch( '< medium' );
const isWideOrHuge = isViewportMatch( '>= wide' );
// Equivalent:
//  const isWideOrHuge = isViewportMatch( 'wide' );

Higher-Order Components

This package provides a set of HOCs to author components whose behavior should vary depending on the viewport.

# ifViewportMatches

Higher-order component creator, creating a new component which renders if the viewport query is satisfied.

Related

• withViewportMatches

Usage

function MyMobileComponent() {
	return <div>I'm only rendered on mobile viewports!</div>;
}

MyMobileComponent = ifViewportMatches( '< small' )( MyMobileComponent );

Parameters

• query string: Viewport query.

Returns

• Function: Higher-order component.

# store

Store definition for the viewport namespace.

Related

• https://github.com/WordPress/gutenberg/blob/HEAD/packages/data/README.md#createReduxStore

Type

• Object

# withViewportMatch

Higher-order component creator, creating a new component which renders with the given prop names, where the value passed to the underlying component is the result of the query assigned as the object's value.

Related

• isViewportMatch

Usage

function MyComponent( { isMobile } ) {
	return (
		<div>Currently: { isMobile ? 'Mobile' : 'Not Mobile' }</div>
	);
}

MyComponent = withViewportMatch( { isMobile: '< small' } )( MyComponent );

Parameters

• queries Object: Object of prop name to viewport query.

Returns

• Function: Higher-order component.