👩‍🎤💍 emotion-media-query

Beautiful media queries better than CSS @media for emotion with ability to specify custom breakpoints.

Don't forget to STAR 🎊 We are working so hard to add more features/customizations to emotion-media-query!

Features:

• Custom breakpoints
• Custom size units (px, em, rem)
• Awesome syntax for min-width and max-width for each breakpoint
• Familiar syntax as it uses Tagged Template Literals just like styled-components
• Ability to convert px to rem or em

This is a fork of styled-media-query by Mohammad Rajabifard. All credit goes to him.

Start

• Installation
• Usage - Get Started
• Concepts
• API
• Tagged Template Literals explained

🌱 Installation

You can install it like every other library with awesome yarn:

yarn add emotion-media-query

or with npm

npm install emotion-media-query

Note: If you didn't install emotion-components yet, install it as well yarn add emotion-components

If you use UglifyJS and it fails or you need compiled module, update to latest version please!

🍃 Usage

First let me mention how our default breakpoint look like:

{
  huge: '1440px',
  large: '1170px',
  medium: '768px',
  small: '450px',
}

The media has 3 main methods to generate media queries:

• lessThan(breakpoint | size)
• greaterThan(breakpoint | size)
• between(firstBreakpoint | firstSize, lastBreakpoint | lastSize)

Basic Example

Probably this example will explain most of this library. You can use one of these methods to write different kinds of media queries like this:

import styled from 'emotion-react'; // You need this as well
import media from 'emotion-media-query';

const Box = styled.div`
  background: black;

  ${media.lessThan('medium')`
    /* screen width is less than 768px (medium) */
    background: red;
  `}

  ${media.between('medium', 'large')`
    /* screen width is between 768px (medium) and 1170px (large) */
    background: green;
  `}

  ${media.greaterThan('large')`
    /* screen width is greater than 1170px (large) */
    background: blue;
  `}
`;

The code above is the same as below in pure CSS:

/* ↓↓↓↓↓↓↓↓↓ */

div {
  background: black;

  @media (max-width: 768px) {
    /* screen width is less than 768px (medium) */
    background: red;
  }

  @media (min-width: 768px) and (max-width: 1170px) {
    /* screen width is between 768px (medium) and 1170px (large) */
    background: green;
  }

  @media (min-width: 1170px) {
    /* screen width is greater than 1170px (large) */
    background: blue;
  }
}

Note: You can use custom size instead of breakpoint names, too.

lessThan

You can use this type of media query to add styles for screen sizes less than given breakpoint or size.

Example with breakpoint:

media.lessThan('medium')`
  /* styles ... */
`

Example with custom size:

media.lessThan('768px')`
  /* styles ... */
`

Note: You can use rem and em too. (Even you can convert breakpoints to use em or rem with pxToRem and pxToEm functions)

greaterThan

You can use it to add styles for screen sizes greater than given breakpoint or size.

Example with breakpoint:

media.greaterThan('small')`
  /* styles ... */
`

Example with custom size:

media.greaterThan('450px')`
  /* styles ... */
`

between

We use between to add styles for screen sizes between the two given breakpoints or sizes.

Example with breakpoints:

media.between('small', 'medium')`
  /* styles ... */
`

Example with custom sizes:

media.between('450px', '768px')`
  /* styles ... */
`

Use with custom breakpoints:

Our breakpoints may not fit your app, so we export another function called generateMedia to generate a media object with your own custom breakpoints:

import styled from 'emotion-react'; // You need this as well
import { generateMedia } from 'emotion-media-query';

const customMedia = generateMedia({
  desktop: '78em',
  tablet: '60em',
  mobile: '46em',
});

// for example call it `Box`
const Box = styled.div`
  font-size: 20px;

  ${customMedia.lessThan('tablet')`
    /* for screen sizes less than 60em */
    font-size: 15px;
  `}
`;

In the case you needed the default breakpoints object, you can import it as follow:

import { defaultBreakpoints } from 'emotion-media-query';

🐽 Concepts

There's a little to learn before you can read the API section.

Breakpoints Object

It's an object containing each break point name as keys and the screen width as values. emotion-media-query exports the defaultBreakpoints object.

Media Generator Object

A media generator object is what is returned from generateMedia function or the default exported object from emotion-media-query. Read API section for each method.

🌼 API

We have a very minimal API, probably you are familiar with 90% of it so far.

Default media

A media generator object with default breakpoints object:

Example:

import media from 'emotion-media-query';

generateMedia

Generates custom media generator object with custom breakpoints:

generateMedia([breakpoints]);

• breakpoints: Object default: defaultBreakpoints - a breakpoints object

Example:

import { generateMedia } from 'emotion-media-query';

const media = generateMedia({
  xs: '250px',
  sm: '450px',
  md: '768px',
  lg: '1200px',
});

pxToRem

Converts breakpoints object's units from px to rem based on the ratio of px to 1rem.

parameters:

• breakpoints: Object - a breakpoints object
• ratio: number default: 16 - how many px is equal to 1rem? (It's your root font-size)

Example:

import { pxToRem } from 'emotion-media-query';

const breakpointsInRem = pxToRem({
  small: '250px',
  medium: '768px',
  large: '1200px',
}, 10);

/* ↓↓ returns ↓↓
{
  small: '25rem',
  medium: '76.8rem',
  large: '120rem',
}
*/

pxToEm

Similar to pxToRem. Converts breakpoints object's units from px to em based on the ratio of px to 1em.

parameters:

• breakpoints: Object - a breakpoints object
• ratio: number default: 16 - how many px is equal to 1em? (Probably it's your root font-size)

Example: Similar to pxToRem.

⚙️ Troubleshoot

If you use UglifyJS and it fails or you need compiled module you need to update your module to v2 right now to fix the issue:

npm install emotion-media-query@latest

🐿 Contributions

I'd love to contribute in open source projects, and love to see people contribute. So any kind of contributions (bug reports, suggestions, PRs, issues, etc) are super welcome.

🍿 TODO

• Write tests with Jest
• Ability to specify custom media attributes
• Add support for glamorous
• ... You say?

License

Licensed under the MIT License, Copyright © 2017 Mohammad Rajabifard.

See LICENSE for more information.