React Match Breakpoints

Lightweight and easy to use media query library for React. Define your media query breakpoints once and use them either as components or as props across your application.

Table of Contents

• Motivation
• Installation
• Usage
• Examples
• Browser Support
• Roadmap
• License

Motivation

React Match Breakpoints (RMB) goal is to provide a consistent way of handling responsiveness in you React app. Though similar in some ways to other solutions like react-responsive or react-media RMB differs in core concepts:

• You should be able to use RMB with ease both as React components and HOC function. Regardless in what way you will be using RMB, your breakpoints configuration should be SSOT.

• RMB should make no assumptions regarding how you media queries should look like. RMB is built on top of matchMedia API so you can pass any media query string that is handled by it. This approach gives you a lot of flexibility and works great with solutions like styled-components since you can declare your media queries once and use them both in your styles and layout.

Installation

$ npm install react-match-breakpoints --save

Usage

Basic usage

First, you have to include Provider that expects object which you have to create using createBreakpoints method.

createBreakpoints accepts an object of which keys will be breakpoints names and values are media query strings.

// index.js

import React from 'react'
import {Provider as BreakpointsProvider, createBreakpoints} from 'react-match-breakpoints'
import App from './App'

const mediaQueries = {
  isMobile: 'screen and (max-width: 767px)',
  isTablet: 'screen and (min-width: 768px) and (max-width: 1024px)'
}

const breakpoints = createBreakpoints(mediaQueries)

ReactDOM.render(
  <BreakpointsProvider breakpoints={breakpoints}>
    <App />
  </BreakpointsProvider>,
  document.getElementById('root'),
)

Now you can access your defined breakpoints either using withBreakpoints HOC or by using Breakpoints component.

withBreakpoints hoc will provide breakpoints prop to the wrapped component which holds the current state of your breakpoints.

Breakpoints component gives you access to your breakpoints by defining them as its properties (it will automatically capitalize breakpoints names).

// App.js

import React, {Component} from 'react'
import {
  Breakpoints, 
  withBreakpoints
} from 'react-match-breakpoints'

class App extends Component {
  componentDidMount() {
    const {breakpoints} = this.props
    
    if(breakpoints.isTablet) {
      // do something when isTablet breakpoint is matched
    }
  }
  render() {
    <div className='container'>
      // Note that component name is capitalized      
      <Breakpoints.IsMobile>
        // children will be rendered 
        // only when `isMobile` breakpoint is matched
        
        <h3>I'm mobile device!</h3>
      </Breakpoints.IsMobile>
      
      <Breakpoints.IsTablet>
        // children will be rendered 
        // only when `isTablet` breakpoint is matched
              
          <h3>I'm tablet!</h3>
        </Breakpoints.IsTablet>
            
      Hello world
    </div>
  }
}

export default withBreakpoints(App)

Customize components names

You can customize the names of Breakpoints components, by providing a function to crateBreakpoints as its second argument. This function will be invoked during each component creation and it receives a default breakpoint name as an argument.

import React from 'react'
import {
  Provider as BreakpointsProvider, 
  createBreakpoints, 
  Breakpoints
} from 'react-match-breakpoints'

const mediaQueries = {
  isMobile: 'screen and (max-width: 767px)',
  isTablet: 'screen and (min-width: 768px) and (max-width: 1024px)'
}

const renameFn = breakpointName => breakpointName.replace('is', '')

const breakpoints = createBreakpoints(mediaQueries, renameFn)

const App = () => (
  <div>
    <Breakpoints.Mobile>
      // will work as usual
    </Breakpoints.Mobile>
  </div>
)

ReactDOM.render(
  <BreakpointsProvider breakpoints={breakpoints}>
    <App />
  </BreakpointsProvider>,
  document.getElementById('root'),
)

Examples

• Using Breakpoints
• Using withBreakpoints
• Renaming Breakpoints
• Accessing non defined Breakpoints

Browser 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.

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

Roadmap

• Debug feature
• Possibility to provide media query as an object
• Flow support
• Server Side Rendering

License

MIT