Breakpoints

Breakpoints serve as adjustable widths that determine the behavior of your responsive layout across different device or viewport sizes.

Preview

For own components.

const Box = styled.div`
  background-color: pink;

  ${({ theme }) => theme.breakpoints.up('sm')} {
    background-color: hotpink;
  }

  ${({ theme }) => theme.breakpoints.up('md')} {
    background-color: red;
  }
`;

For third party components.

const Layout = () => {
  const theme = useTheme();
  const isMd = useMediaQuery(theme.breakpoints.up('md'));

  return <>{isMd && <Box />}</>;
};

Examples

Mobile First

From smallest to largest

Desktop First

From largest to smallest

hooks API

Documentation

• quick start
• migration from v11
• core concepts
• available breakpoints
• media queries
  • min-width
  • max-width
  • single breakpoint
  • between breakpoints
  • useMediaQuery hook
• customization
  • breakpoints
  • merge with another theme

Quick start

npm install styled-components styled-breakpoints

# or

yarn add styled-components styled-breakpoints

import 'styled-components';
import { StyledBreakpointsTheme } from 'styled-breakpoints';

declare module 'styled-components' {
  export interface DefaultTheme extends StyledBreakpointsTheme {}
}

import styled { ThemeProvider } from 'styled-components';
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

const Block = styled.div`
  display: none;

  ${({ theme }) => theme.breakpoints.up('sm')} {
    display: block;
  }
`

const theme = createStyledBreakpointsTheme();

const App = () => (
  <ThemeProvider theme={theme}>
    <Block/>
  </ThemeProvider>
)

npm install @emotion/{styled,react} styled-breakpoints

# or

yarn add @emotion/{styled,react} styled-breakpoints

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

declare module '@emotion/react' {
  export interface Theme extends StyledBreakpointsTheme {}
}

import styled from '@emotion/styled';
import { ThemeProvider } from '@emotion/react';
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

const Block = styled.div`
  display: none;

  ${({ theme }) => theme.breakpoints.up('sm')} {
    display: block;
  }
`;

const theme = createStyledBreakpointsTheme();

const App = () => (
  <ThemeProvider theme={theme}>
    <Block />
  </ThemeProvider>
);

Migration from v11

Theme

The createTheme function has been replaced with createStyledBreakpointsTheme.

- import { createTheme } from "styled-breakpoints";

- const theme = createTheme();



+ import { createStyledBreakpointsTheme } from "styled-breakpoints";

+ const theme = createStyledBreakpointsTheme();

Media Queries

Additionally, the functions up, down, between, and only have been moved to the theme object. This means that you no longer need to import them individually each time you want to use them.

- import { up } from "styled-breakpoints";

- const Box = styled.div`
-  ${up('md')} {
-     background-color: red;
-  }


+ const Box = styled.div`
+  ${({ theme }) => theme.breakpoints.up('md')} {
+     background-color: red;
+  }
`

Hooks

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

or

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

- const Example = () => {
-   const isMd = useBreakpoint(only('md'));
-
-   return <Layout>{isMd && </Box>}</Layout>
- }

+ import { useMediaQuery } from 'styled-breakpoints/use-media-query';

+ const Example = () => {
+   const theme = useTheme();
+   const isMd = useMediaQuery(theme.breakpoints.only('md'));
+
+   return <Layout>{isMd && </Box>}</Layout>
+ }

Core concepts

• Breakpoints act as the fundamental elements of responsive design. They enable you to control when your layout can adapt to a specific viewport or device size.

• Utilize media queries to structure your CSS based on breakpoints. Media queries are CSS features that allow you to selectively apply styles depending on a defined set of browser and operating system parameters. The most commonly used media query property is min-width.

• The objective is mobile-first, responsive design. Styled Breakpoints aims to apply the essential styles required for a layout to function at the smallest breakpoint. Additional styles are then added to adjust the design for larger devices. This approach optimizes your CSS, enhances rendering speed, and delivers an excellent user experience.

Available breakpoints

Styled Breakpoints includes six default breakpoints, often referred to as grid tiers, for building responsive designs. These breakpoints can be customized.

Each breakpoint has been carefully selected to accommodate containers with widths that are multiples of 12. The breakpoints also represent a subset of common device sizes and viewport dimensions, although they do not specifically target every use case or device. Instead, they provide a robust and consistent foundation for building designs that cater to nearly any device.

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

Media queries

Min-width

  declare function up(
    min: string,
    orientation?: 'portrait' | 'landscape'
  ) => string

const Block = styled.div`
  display: none;

  ${({ theme }) => theme.breakpoints.up('sm')} {
    display: block;
  }
`;

@media (min-width: 768px) {
  display: block;
}

Max-width

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

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

const Block = styled.div`
  display: block;

  ${({ theme }) => theme.breakpoints.down('md')} {
    display: none;
  }
`;

@media (max-width: 767.98px) {
  display: none;
}

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.

Single breakpoint

There are also media queries and mixins for targeting a single segment of screen sizes using the minimum and maximum breakpoint widths.

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

const Block = styled.div`
  background-color: pink;

  ${({ theme }) => theme.breakpoints.only('md')} {
    background-color: rebeccapurple;
  }
`;

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

Between breakpoints

Similarly, media queries may span multiple breakpoint widths.

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

const Block = styled.div`
  background-color: gold;

  ${({ theme }) => theme.breakpoints.between('md', 'xl')} {
    background-color: rebeccapurple;
  }
`;

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

useMediaQuery hook

features:

• 🧐 optimal performance by dynamically monitoring document changes in media queries.
• ⚙️ It supports SSR (server-side rendering).
• 📦 Minified and gzipped size 323b.

 declare function useMediaQuery(query: string) => boolean

import { useTheme } from 'styled-components'; // or '@emotion/react'
import { useMediaQuery } from 'styled-breakpoints/use-media-query';
import { Box } from 'third-party-library';

const SomeComponent = () => {
  const theme = useTheme();
  const isMd = useMediaQuery(theme.breakpoints.only('md'));

  return <AnotherComponent>{isMd && <Box />}</AnotherComponent>;
};

Customization

Breakpoints

import styled from 'styled-components';
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

const theme = createStyledBreakpointsTheme({
  breakpoints: {
    small: '0px',
    medium: '640px',
    large: '1024px',
    xLarge: '1200px',
    xxLarge: '1440px',
  },
});

const Block = styled.div`
  background-color: pink;

  ${({ theme }) => theme.breakpoints.up('medium')} {
    background-color: hotpink;
  }
`;

const App = () => (
  <ThemeProvider theme={theme}>
    <Block />
  </ThemeProvider>
);

Merge with another theme

import { ThemeProvider } from 'styled-components';
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

export const primaryTheme = {
  fonts: ['sans-serif', 'Roboto'],
  fontSizes: {
    small: '1em',
    medium: '2em',
    large: '3em',
  },
} as const;

const const theme = {
  ...primaryTheme,
  ...createStyledBreakpointsTheme(),
}

const App = () => (
  <ThemeProvider theme={theme}>
    <Block />
  </ThemeProvider>
);

import 'styled-components';
import { StyledBreakpointsTheme } from 'styled-breakpoints';
import { primaryTheme } from './app';

type PrimaryTheme = typeof primaryTheme;

declare module 'styled-components' {
  export interface DefaultTheme extends PrimaryTheme, StyledBreakpointsTheme {}
}

import { ThemeProvider } from '@emotion/react';
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

export const primaryTheme = {
  fonts: ['sans-serif', 'Roboto'],
  fontSizes: {
    small: '1em',
    medium: '2em',
    large: '3em',
  },
} as const;

const const theme = {
  ...primaryTheme,
  ...styledBreakpointsTheme(),
}

const App = () => (
  <ThemeProvider theme={theme}>
    <Block />
  </ThemeProvider>
);

import '@emotion/react';
import { StyledBreakpointsTheme } from 'styled-breakpoints';
import { primaryTheme } from './app';

type PrimaryTheme = typeof primaryTheme;

declare module '@emotion/react' {
  export interface Theme extends PrimaryTheme, StyledBreakpointsTheme {}
}

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!