🌼 Preview

Inside components.

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

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

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

Outside components.

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

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

return <>{isMd && };
};
`

Examples

$3

From smallest to largest







$3

From largest to smallest







$3







📖 Documentation

- core concepts
- 🚩 getting started
- Media Queries API
- min-width - up
- max-width - down
- single breakpoint - only
- breakpoints range - between
- customization

- useMediaQuery hook

🧐 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.

Getting Started

$3

`sh
npm install styled-breakpoints@latest

or

yarn add styled-breakpoints@latest
`

$3

#### 🚩 File Structure

`js
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.

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

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.

#### 🚩 Default Configuration

theme/index.ts

`tsx
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

export const theme = createStyledBreakpointsTheme();
`

theme/index.ts

`tsx
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

export const theme = createStyledBreakpointsTheme({
breakpoints: {
small: '100px',
medium: '200px',
large: '300px',
xLarge: '400px',
xxLarge: '500px',
},
});
`

##### 🎨 Merge with Another Theme

theme/index.ts

`tsx
import { createStyledBreakpointsTheme } from 'styled-breakpoints';

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

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

`sh
npm install styled-components

or

yarn add styled-components
`

theme/styled.d.ts

`ts
import 'styled-components';
import { theme } from './index';

type ThemeConfig = typeof theme;

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

`sh
npm install @emotion/{styled,react}

or

yarn add @emotion/{styled,react}
`

theme/emotion.d.ts

`ts
import '@emotion/react';
import { theme } from './index';

type ThemeConfig = typeof theme;

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

app.tsx

`tsx
import styled { ThemeProvider } from 'styled-components'; // or '@emotion/react'
import { theme } from './theme';

const Box = styled.div
display: none;

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

const App = () => (



);
`

Media queries API

🚀 Caching is implemented in all functions to optimize performance.

$3

`tsx
const Box = styled.div
display: none;

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



Will convert to vanilla css:

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

`tsx
const Box = styled.div
display: block;

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



Will convert to vanilla css:

`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.

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

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



Will convert to vanilla css:

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

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

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



Will convert to vanilla css:

`css
@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 313b.

`tsx
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 { only } = useTheme().breakpoints;
const isMd = useMediaQuery(only('md'));

return {isMd && };
};
`

$3

#### Type Declarations

`ts
declare function useMediaQuery(
query: string,
options?: {
defaultValue?: boolean;
initializeWithValue?: boolean;
}
): boolean;
`

#### Arguments

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

- options _(optional)_
- defaultValue _(default: false)_
Value used during SSR and as a fallback.

- initializeWithValue _(default: true)_
Whether to evaluate the media query immediately on the client.
Set to false in SSR scenarios to avoid hydration mismatch.

#### Returns

- boolean
true` if the media query currently matches the viewport.

License

MIT License

Copyright (c) 2018-2025 Maxim Alyoshin.

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 🐛