Skip to content

Latest commit

 

History

History
333 lines (230 loc) · 8.13 KB

README.md

File metadata and controls

333 lines (230 loc) · 8.13 KB
Raw

💅💍 styled-media-query

npm npm David with-coffee with-love

Beautiful media queries better than CSS @media for styled-components with ability to specify custom breakpoints.

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

Note: This documentation is for the latest version (v2). We still support v1 syntax but it'll be removed in v3.

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

Start

🌱 Installation

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

yarn add styled-media-query

or with npm

npm install styled-media-query

Note: If you didn't install styled-components yet, install it as well yarn add styled-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:

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 "styled-components"; // You need this as well
import media from "styled-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 "styled-components"; // You need this as well
import { generateMedia } from "styled-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 "styled-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. styled-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 styled-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 "styled-media-query";

generateMedia

Generates custom media generator object with custom breakpoints:

generateMedia([breakpoints]);

Example:

import { generateMedia } from "styled-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 "styled-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 styled-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

  • Add convertors for em and rem to px and vice-versa.
  • Add between() method
  • Add LICENSE
  • 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.