React Match Breakpoints

Lightweight, performant and easy to use media query library for React📱 💻 🖥️

_{Define breakpoints configuration once using standard media queries and use it across your project either as components, hooks, HOC, or by simply passing configuration dictionary around.}

Table of contents

• Motivation
• Installation
• Basic usage
• Support
• Usage with Typescript
• Usage with SSR
• API
• License

Motivation

React Match Breakpoints (RMB) goal is to provide a consistent way of handling responsiveness in your React app. RMB works great with CSS-in-JS libraries like styled-components, but you can also find it useful in every tech stack of your choosing. Some highlights:

• Universal - can be used with ease both in declarative and imperative code. You can use it as a Component, HOC, or hook. It also handles SSR well

• Consistent - regardless of how it will be used, initial configuration is SSOT.

• Flexible - allows any media query string that is supported by matchMedia method

• Performant - built on top of matchMedia API. No window.onresize handlers

• Lightweight - no dependencies and it only weighs around 2kb (minified and gzipped)

• Mature - Build using Typescript and tested

Installation

$ npm install react-match-breakpoints

or

$ yarn add react-match-breakpoints

Basic usage

To initialize RMB use initBreakpoints method and wrap your application with returned Provider.

⚠️ notice that initBreakpoints is called before the actual app starts to render. This is an intentional and required way of setting up RMB ⚠️

import React from 'react'
import { initBreakpoints } from 'react-match-breakpoints'
import App from './App'

const breakpointsConfig = {
  mobile: 'screen and (max-width: 767px)',
  tablet: 'screen and (min-width: 768px) and (max-width: 1024px)',
}

const BreakpointsProvider = initBreakpoints(breakpointsConfig)

ReactDOM.render(
  <BreakpointsProvider>
    <App />
  </BreakpointsProvider>,
  document.getElementById('root'),
)

Using Breakpoint component:

Breakpoint is a singleton and is aware of the configuration that you provided to initBreakpoints method

import React from 'react'
import { Breakpoint } from 'react-match-breakpoints'

const ResponsiveComponent = () => {
  return (
    <Breakpoint.mobile>
      <span>I will be shown on mobile devices</span>
    </Breakpoint.mobile>

    <Breakpoint.tablet>
      <span>I will be shown on tablet devices</span>
    </Breakpoint.tablet>
  )
}

Using useBreakpoints hook

import React from 'react'
import { useBreakpoints } from 'react-match-breakpoints'

const ResponsiveComponent = () => {
  const breakpoints = useBreakpoints()

  const text = breakpoints.mobile ? 'I will be showed on mobile devices' : 'I will be showed on nonmobile devices'

  return <span>{text}</span>
}

Using withBreakpoints HOC

import React from 'react'
import { withBreakpoints } from 'react-match-breakpoints'

const ResponsiveComponent = props => {
  const text = props.breakpoints.mobile ? 'I will be shown on mobile devices' : 'I will be shown on other devices'

  return <span>{text}</span>
}

export default withBreakpoints(ResponsiveComponent)

Support

RMB is supported basically by every browser that implements the full ES5 spec. It might be a good idea to include matchMedia polyfill for some older browsers.

⚠️ On browsers that don't support Proxy you won't see warnings if you try to access Breakpoints components that are not defined ⚠️

Usage with Typescript

To fully utilize RMB Typescript support you will have to inform RMB of your breakpoints configuration structure. You could do that using declaration merging. First, let's create rmb.d.ts file and extend UserConfig type:

// rmb.d.ts
import { UserConfig } from 'react-match-breakpoints'

declare module 'react-match-breakpoints' {
  export interface UserConfig extends {
    mobile: string,
    tablet: string
  }
}

If you don't want to maintain types separately from your configuration dictionary you can pass it using typeof operator:

// rmb.d.ts
import { UserConfig } from 'react-match-breakpoints'
import config from './breakpoints-config.ts'

type BreakpointsConfig = typeof config

declare module 'react-match-breakpoints' {
  export interface UserConfig extends BreakpointsConfig {}
}

Usage with SSR

RMB can be used together with Server Side Rendering. You have to provide additional breakpoints configuration specific to a server environment. It has to have the same structure as primary configuration with boolean values

import React from 'react'
import { initBreakpoints } from 'react-match-breakpoints'
import App from './App'

const breakpointsConfig = {
  mobile: 'screen and (max-width: 767px)',
  tablet: 'screen and (min-width: 768px) and (max-width: 1024px)',
}

const serverBreakpointsConfig = {
  mobile: true,
  tablet: false,
}

const BreakpointsProvider = initBreakpoints(breakpointsConfig, {
  ssr: {
    config: serverBreakpointsConfig,
  },
})

ReactDOM.render(
  <BreakpointsProvider>
    <App />
  </BreakpointsProvider>,
  document.getElementById('root'),
)

Additionally, you can try to guess the breakpoint during server render using libraries such as useragent. If the breakpoint is guessed incorrectly RMB automatically rerenders this component to show the actual state. This behavior could be disabled using ssr.rehydrate option set to false

API

initBreakpoints(Config, Options)

Used for initializing RMB. Has to be invoked before your application first render

Config

Configuration object. All values should be proper media query strings that could be interpreted by matchMedia method

Options

Options object

Property	Default value	Description
breakpointCSSClass	false	Controls adding css class to Breakpoint children. Could be useful for example during SSR to visually hide badly guessed breakpoints
log	process.env.NODE_ENV !== 'production'	Controls debug mode. By default, RMB shows logs only in the development environment
isServer	typeof window === 'undefined'	Tells RMB if matchMedia should be used or not
ssr.rehydrate	true	By default RMB will rerender badly guessed breakpoints during SSR. You can turn this behavior off by setting this value to false
ssr.config	null	SSR configuration object that should resemble the main Config with boolean values

Arguments

Config (Object): configuration object. See below for details Options (Object): options object. See below for details

Returns

Provider: Provider that has to wrap your application

Example

{
  breakpointCSSClass: false
  log: process.env.NODE_ENV !== 'production',
  isServer: typeof window === 'undefined',
  ssr: {
    rehydrate: false,
    config: null,
  },
}

Breakpoint

Used for accessing Components created from your configuration. Every child of the component will be shown or hidden depending on provided media queries.

Returns

FunctionComponent | nested config part

Example:

import React from 'react'
import { Breakpoint } from 'react-match-breakpoints'

// Provided configuration

// {
//   mobile: {
//     small: 'screen and (max-width: 320px)',
//     big: 'screen and (max-width: 425px)'
//   },
//   tablet: 'screen and (max-width: 425px)'
// }

const ResponsiveComponent = () => {
  return (
    <>
      <Breakpoint.mobile.small>I will be shown on small mobile devices</Breakpoint.mobile.small>

      <Breakpoint.mobile.big>I will be shown on big mobile devices</Breakpoint.mobile.big>

      <Breakpoint.tablet>I will be shown on tablet devices</Breakpoint.tablet>
    </>
  )
}

useBreakpoints()

Hook used for obtaining current breakpoints state.

Returns

Object: An object that resembles provided configuration with boolean values.

Example

import React from 'react'
import { useBreakpoint } from 'react-match-breakpoints'

// Provided configuration

// {
//   mobile: {
//     small: 'screen and (max-width: 320px)',
//     big: 'screen and (max-width: 425px)'
//   },
//   tablet: 'screen and (max-width: 425px)'
// }

const ResponsiveComponent = () => {
  const { mobile, tablet} = useBreakpoints()

  const text = mobile.small
    ? 'I will be shown on mobile devices'
    : tablet
    ? 'I will be shown on tablet devices'
    : 'I will be shown on non-mobile devices' '

  return <span>{text}</span>
}

License

MIT, Copyright © 2018-present Michal Klim