# Viewport

Viewport is a module for responding to changes in the browser viewport size. It registers its own [data module](https://github.com/WordPress/gutenberg/tree/HEAD/packages/data/README.md), 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

```bash
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 such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._

## 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`.

```js
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 `>=`.

```js
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.

<!-- START TOKEN(Autogenerated API docs) -->

#### ifViewportMatches

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

_Related_

-   withViewportMatches

_Usage_

```jsx
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_

```jsx
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.

<!-- END TOKEN(Autogenerated API docs) -->

## Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>