Skip to content

mg901/styled-breakpoints

master
Switch branches/tags
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 


styled-breakpoints
GitHub Workflow Status coverage status npm bundle size npm downloads npm version

Simple and powerful tool for creating media queries with

styled-components     OR    emotion

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

Getting Started

API

Examples

Mobile First

From smallest to largest

Edit mobile-first

Desktop First

From largest to smallest

Edit desktop first example

Hooks API

Styled Components

Hooks api (styled-components)

Emotion

Hooks api (Emotion)

Installation

npm install styled-breakpoints

# or

yarn add styled-breakpoints

# or

pnpm 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;
  }
`;

Customization

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

const theme = createTheme({
  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

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

Type declaration
  declare function 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

Type declaration
  declare function down(
    max: string,
    orientation?: 'portrait' | 'landscape'
  ) => any

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.

css`
  ${down('md')} {
    background-color: rebeccapurple;
  }
`;
Convert to:
@media (max-width: 767.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

Type declaration
 declare function between(
    min: string,
    max: string,
    orientation?: 'portrait' | 'landscape'
  ) => any

Similarly, media queries may span multiple breakpoint widths:

css`
  ${between('md', 'xl')} {
    background-color: rebeccapurple;
  }
`;
Convert to:
@media (min-width: 768px) and (max-width: 1199.98px) {
  background-color: rebeccapurple;
}

only

Type declaration
  declare function only(
    name: string,
    orientation?: 'portrait' | 'landscape'
  ) => any

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

css`
  ${only('md')} {
    background-color: rebeccapurple;
  }
`;
Convert to:
@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

Copyright (c) 2018-2019 Maxim Alyoshin.

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

💻

Buck DeFore

🤔

Pierre Burel

🐛

Konstantin

🐛 💻

Pawel Kochanek

🐛 💻

This project follows the all-contributors specification. Contributions of any kind welcome!