styled-breakpoints

Powerful CSS-in-JS media queries with SSR support.

    OR   

🌼 Preview

Inline in styles.

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

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

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

Via the hook.

import { useTheme } from 'styled-components'; // or '@emotion/react'

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

👉🏻 Hook API

📖 Documentation

• core concepts

• 🚩 getting started

• Media Queries API

  • min-width - up
  • max-width - down
  • single breakpoint - only
  • range of breakpoints - between
  • customization

• useMediaQuery hook

🧐 Core concepts

• Breakpoints are the foundation of responsive design. They let you control when your layout adapts to a specific viewport or device size.

• Use media queries to structure your CSS around breakpoints. Media queries are a CSS feature that lets you apply styles conditionally based on browser and device parameters — most commonly min-width.

• The goal is mobile-first responsive design. Styled Breakpoints applies the essential styles needed at the smallest breakpoint first, then progressively adds styles for larger screens. This keeps your CSS lean, improves rendering speed, and delivers a better user experience.

Getting Started

🚩 Installation

npm install styled-breakpoints@latest

# or

yarn add styled-breakpoints@latest

Configuration

🚩 File Structure

 theme/
 ├── index.ts
 └── styled.d.ts // or emotion.d.ts
 app.tsx

🚩 Available breakpoints

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

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

Each breakpoint follows common responsive design conventions, with widths that are multiples of 12. They align with widely used viewport ranges but aren't tied to specific devices — just a consistent foundation for layouts that work across most screen sizes.

🚩 Default Configuration

theme/index.ts

import { createStyledBreakpointsTheme } from 'styled-breakpoints';

export const theme = createStyledBreakpointsTheme();

---

Customization

🚩 Breakpoints

theme/index.ts

import { createStyledBreakpointsTheme } from 'styled-breakpoints';

export const theme = createStyledBreakpointsTheme({
  breakpoints: {
    values: {
      watch: '0px',
      mobile: '200px',
      tablet: '600px',
      laptop: '900px',
      desktop: '1400px',
    },
  },
});

🎨 Merge with Another Theme

theme/index.ts

import { createStyledBreakpointsTheme } from 'styled-breakpoints';

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

export const theme = {
  ...mainTheme,
  ...createStyledBreakpointsTheme(),
};

export type AppThemeType = typeof theme;

---

💅 Using with Styled Components

🚩 Installation

npm install styled-components

# or

yarn add styled-components

theme/styled.d.ts

import 'styled-components';
import { AppThemeType } from './index';

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

---

👩‍🎤 Using with Emotion

🚩 Installation

npm install @emotion/{styled,react}

# or

yarn add @emotion/{styled,react}

theme/emotion.d.ts

import '@emotion/react';
import { AppThemeType } from './index';

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

---

🚀 Integration into Your App

app.tsx

import { ThemeProvider } from 'styled-components'; // or '@emotion/react'
import styled from 'styled-components'; // or '@emotion/styled'

import { theme } from './theme';

const Box = styled.div`
  display: none;

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

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

Media queries API

🚀 All media query functions cache their results to improve performance.

Min-width - up

const Box = styled.div`
  display: none;

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

Will be converted to CSS:

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

---

Max-width - down

Sometimes you need a media query that goes the other direction (the given screen size or smaller):

const Box = styled.div`
  display: block;

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

Will be converted to CSS:

@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 - only

There's also a way to target a single segment of screen sizes using the minimum and maximum breakpoint widths.

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

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

Will be converted to CSS:

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

---

Range of breakpoints - between

Use between to target a range of breakpoints.

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

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

Will be converted to CSS:

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

---

👉🏻 useMediaQuery hook

features:

• 🧐 Reactive media query tracking, optimized for performance
• 💪🏻 Safe for SSR via getServerSnapshot
• 📦 Lightweight, minimal overhead

import { useTheme } from 'styled-components'; // or from '@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 <Box>{isMd && <Box />}</Box>;
};

API

Type Declarations

declare function useMediaQuery(
  query: string,
  options?: {
    getServerSnapshot: () => boolean;
  }
): boolean;

Arguments

• query
  CSS media query to evaluate.
  Accepts values with or without the @media prefix.

• options (optional)

  • getServerSnapshot
    Function used during SSR to provide a stable boolean value for the initial render.

Returns

• boolean
true if the media query currently matches the viewport.

---

License

MIT License

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

---

Contributors

mg901 💬 💻 🎨 📖 💡 🚇 🚧 📆 📣 🔬 👀 ⚠️ 🔧 ✅	Abu Shamsutdinov 🐛 💻 💡 🤔 👀 📢	Sova 💻 💡 🤔 👀 📢	Jussi Kinnula 🐛 💻	Rafał Wyszomirski 📖	Adrian Celczyński 🐛 💻	Sam Holmes 💻 🤔
Ontopic 🤔	Ryan Bell 🤔	Bart Nagel 🐛 💻 💡 🤔	Greg McKelvey 💻	Buck DeFore 🤔	Pierre Burel 🐛	Pawel Kochanek 🐛 💻
Ian Christopher B. de Jesus 🐛	David de Lusenet 🐛 🤔	Dan Adler 🐛