# @react-hook/media-query

> React hooks that update when media queries change between matched and unmatched states.

Latest version **1.1.1** (published 2020-07-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @react-hook/media-query
pnpm add @react-hook/media-query
yarn add @react-hook/media-query
bun add @react-hook/media-query
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2020-07-17 |
| First published | 2020-01-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 78.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1529 |
| Author | Jared Lunde |
| Maintainers | jaredlunde |
| Keywords | react, react hook, media query, matchmedia, media query hook, react media query hook, media queries hook, media queries, javascript media query, media query js, breakpoint hook, breakpoints hook, react breakpoint, react breakpoints |

## Links

- npm: https://www.npmjs.com/package/@react-hook/media-query
- Repository: https://github.com/jaredLunde/react-hook
- Homepage: https://github.com/jaredLunde/react-hook/tree/master/packages/media-query#readme
- Issues: https://github.com/jaredLunde/react-hook/issues
- npm.io page: https://npm.io/package/@react-hook/media-query

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.1.1 (latest) — 2020-07-17
- 1.1.0 — 2020-06-07
- 1.0.1 — 2020-01-24
- 1.0.0 — 2020-01-24

## README

<hr>
<div align="center">
  <h1 align="center">
    useMediaQuery()
  </h1>
</div>

<p align="center">
  <a href="https://bundlephobia.com/result?p=@react-hook/media-query">
    <img alt="Bundlephobia" src="https://img.shields.io/bundlephobia/minzip/@react-hook/media-query?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="Types" href="https://www.npmjs.com/package/@react-hook/media-query">
    <img alt="Types" src="https://img.shields.io/npm/types/@react-hook/media-query?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="Build status" href="https://travis-ci.com/jaredLunde/react-hook">
    <img alt="Build status" src="https://img.shields.io/travis/com/jaredLunde/react-hook?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="NPM version" href="https://www.npmjs.com/package/@react-hook/media-query">
    <img alt="NPM Version" src="https://img.shields.io/npm/v/@react-hook/media-query?style=for-the-badge&labelColor=24292e">
  </a>
  <a aria-label="License" href="https://jaredlunde.mit-license.org/">
    <img alt="MIT License" src="https://img.shields.io/npm/l/@react-hook/media-query?style=for-the-badge&labelColor=24292e">
  </a>
</p>

<pre align="center">npm i @react-hook/media-query</pre>
<hr>

React hooks that update when media queries change between matched and unmatched states.

## Quick Start

```jsx harmony
import {useMediaQuery, useMediaQueries} from '@react-hook/media-query'

// Using a single media query
const Component = () => {
  const matches = useMediaQuery('only screen and (min-width: 400px)')
  return `Matches? ${matches ? 'Matched!' : 'Nope :(')}`
}

// Using multiple media queries
const Component = () => {
  const {matches, matchesAny, matchesAll} = useMediaQueries({
    screen: 'screen',
    width: '(min-width: 400px)'
  })

  return (
    <div>
      Screen matched? {matches.screen ? 'Yes' : 'No'}
      Width matched? {matches.width ? 'Yes' : 'No'}
      All matched? {matchesAll ? 'Yes' : 'No'}
      Any matched? {matchesAny ? 'Yes' : 'No'}
    </div>
  )
}
```

## API

### useMediaQuery(query)

A hook that returns `true` if the media query matched and `false` if not. This hook
will always return `false` when rendering on the server.

| Argument | Type     | Required? | Description                                                                          |
| -------- | -------- | --------- | ------------------------------------------------------------------------------------ |
| query    | `string` | Yes       | The media query you want to match against e.g. `"only screen and (min-width: 12em)"` |

#### Returns `boolean`

Returns `true` if the media query matched. This is always `false` when rendering on the server.

### useMediaQueries(queryMap)

A hook that returns a [`MediaQueryMatches`](#mediaquerymatches) object which will
tell you if specific media queries matched, all media queries matched, or
any media queries matched. Matches in this hook will always return `false` when
rendering on the server.

| Argument | Type                          | Required? | Description                                                                                       |
| -------- | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| queryMap | `{[Name in keyof T]: string}` | Yes       | The media queries you want to match against e.g. `{screen: "screen", width: "(min-width: 12em)"}` |

#### Returns [`MediaQueryMatches`](#mediaquerymatches)

### MediaQueryMatches

```typescript
export interface MediaQueryMatches<T> {
  /**
   * Returns a map of query key/didMatch pairs
   */
  matches: Matches<T>
  /**
   * `true` if any of the media queries matched
   */
  matchesAny: boolean
  /**
   * `true` if all of the media queries matched
   */
  matchesAll: boolean
}
```

## LICENSE

MIT

---
_Source: https://npm.io/package/@react-hook/media-query · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._