README

styled-breakpoints

Simple and powerful tool for creating media queries with

Core concepts

Breakpoints are the building blocks of responsive design. Use them to control when your layout can be adapted at a particular viewport or device size.

Use media queries to architect your CSS by breakpoint. Media queries are a feature of CSS that allow you to conditionally apply styles based on a set of browser and operating system parameters. We most commonly use min-width in our media queries.

Mobile first, responsive design is the goal. Styled Breakpoints aims to apply the bare minimum of styles to make a layout work at the smallest breakpoint, and then layers on styles to adjust that design for larger devices. This optimizes your CSS, improves rendering time, and provides a great experience for your visitors.

Documentation

Examples

mobile first
desktop first
hooks api

Getting Started

Installation
default breakpoints
custom breakpoints
object notation

API

up
down
between
only
useBreakpoint

Examples

Mobile First

From smallest to largest

Desktop First

From largest to smallest

Hooks API

Styled Components

Emotion

Installation

npm install styled-breakpoints

# or

yarn add styled-breakpoints

Available breakpoints

Styled Breakpoints includes six default breakpoints, sometimes referred to as grid tiers, for building responsively. These breakpoints can be customized. Each breakpoint was chosen to comfortably hold containers whose widths are multiples of 12. Breakpoints are also representative of a subset of common device sizes and viewport dimensions they don’t specifically target every use case or device. Instead, the ranges provide a strong and consistent foundation to build on for nearly any device.

const defaultBreakpoints = {
  xs: '0px',
  sm: '576px',
  md: '768px',
  lg: '992px',
  xl: '1200px',
  xxl: '1400px',
};

import { up, down, between, only } from 'styled-breakpoints';

const Component = styled.div`
  color: black;

  ${only('md')} {
    color: rebeccapurple;
  }
`;

Custom breakpoints

import { up, down, between, only } from 'styled-breakpoints';

const theme = {
  breakpoints: {
    sm: '576px',
    md: '768px',
    lg: '992px',
    xl: '1200px',
  },
};

const Component = styled.div`
  color: black;

  ${only('sm')} {
    color: rebeccapurple;
  }

  ${between('sm', 'md')} {
    color: hotpink;
  }

  ${down('lg')} {
    color: lightcoral;
  }

  ${up('xl')} {
    color: hotpink;
  }
`;

<ThemeProvider theme={theme}>
  <Component>This is cool!</Component>
</ThemeProvider>;

Object notation

When using object notation, make sure to explicitly pass props to breakpoint methods. Please see the example below using default configuration:

import { down, between } from 'styled-breakpoints';

const Component = styled('div')((props) => ({
  color: 'black',
  [down('md')(props)]: {
    color: 'lightcoral',
  },
  [between('sm', 'md')(props)]: {
    color: 'hotpink',
  },
}));

Hooks API

Styled Components

import { useBreakpoint } from 'styled-breakpoints/react-styled';

Emotion

import { useBreakpoint } from 'styled-breakpoints/react-emotion';

API

Core API is inspired by Bootstrap responsive breakpoints.

For example, let's take default values of breakpoints.

up

// const up = (min: string, orientation?: 'portrait' | 'landscape') => any

css`
  ${up('md')} {
    background-color: rebeccapurple;
  }
`;

Convert to pure css:

@media (min-width: 768px) {
  background-color: rebeccapurple;
}

down

We occasionally use media queries that go in the other direction (the given screen size or smaller).

This function takes this declared breakpoint, subtracts 0.02px from it, and uses it as the maximum width value.

// const down = (max: string, orientation?: 'portrait' | 'landscape') => any

css`
  ${down('md')} {
    background-color: rebeccapurple;
  }
`;

Convert to pure css:

@media (max-width: 991.98px) {
  background-color: rebeccapurple;
}

Why subtract .02px? Browsers don’t currently support range context queries, so we work around the limitations of min- and max- prefixes and viewports with fractional widths (which can occur under certain conditions on high-dpi devices, for instance) by using values with higher precision.

between

Similarly, media queries may span multiple breakpoint widths:

// const between = (min: string, max: string, orientation?: 'portrait' | 'landscape') => any

css`
  ${between('md', 'lg')} {
    background-color: rebeccapurple;
  }
`;

Convert to pure css:

@media (min-width: 768px) and (max-width: 1199.98px) {
  background-color: rebeccapurple;
}

only

There is also function for targeting a single segment of screen sizes using the minimum and maximum breakpoint widths.

// const only = (name: string, orientation?: 'portrait' | 'landscape') => any

css`
  ${only('md')} {
    background-color: rebeccapurple;
  }
`;

Convert to pure css:

@media (min-width: 768px) and (max-width: 991.98px) {
  background-color: rebeccapurple;
}

useBreakpoint

/**
 * @param {function} up | down | between | only
 *
 * @return {(boolean|null)} `true` if currently matching the given query,
 *                          `false` if not, and `null` if unknown (such as
 *                          during server-side rendering)
 */
useBreakpoint(up('md')) => boolean | null

Other

License

MIT License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributors

Thanks goes to these wonderful people (emoji key):

_Maxim 💻 🎨 📖 💡 🤔 📢	_{Abu Shamsutdinov} 💻 💡 🤔 👀 📢	_{Sergey Sova} 💻 💡 🤔 👀 📢	_{Jussi Kinnula} 🐛 💻	_{Rafał Wyszomirski} 📖	_{Adrian Celczyński} 🐛 💻	_{Alexey Olefirenko} 💻 🤔
_samholmes 💻 🤔	_Ontopic 🤔	_{Ryan Bell} 🤔	_{Bart Nagel} 🐛 💻 💡 🤔	_{Greg McKelvey} 💻