styled-breakpoints

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

## 🌼 Preview **Inline** in styles. ```tsx 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**. ```tsx import { useTheme } from 'styled-components'; // or '@emotion/react' const Layout = () => { const theme = useTheme(); const isMd = useMediaQuery(theme.breakpoints.up('md')); return <>{isMd && }; }; ```
## Examples ### 👉🏻 Mobile First From smallest to largest

### 👉🏻 Desktop First From largest to smallest

### 👉🏻 Hook API

## 📖 Documentation - [core concepts](#core-concepts) - 🚩 [getting started](#getting-started) - [Media Queries API](#media-queries-api) - [min-width - up](#min-width---up) - [max-width - down](#max-width---down) - [single breakpoint - only](#single-breakpoint---only) - [range of breakpoints - between](#range-of-breakpoints---between) - [customization](#customization) - [useMediaQuery hook](#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 ```sh npm install styled-breakpoints@latest # or yarn add styled-breakpoints@latest ```
### Configuration #### 🚩 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](#customization). ```tsx 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` ```tsx import { createStyledBreakpointsTheme } from 'styled-breakpoints'; export const theme = createStyledBreakpointsTheme(); ```

#### Customization ##### 🚩 Breakpoints `theme/index.ts` ```tsx 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` ```tsx 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 ```sh npm install styled-components # or yarn add styled-components ```
`theme/styled.d.ts` ```ts import 'styled-components'; import { AppThemeType } from './index'; declare module 'styled-components' { export interface DefaultTheme extends AppThemeType {} } ```

👩‍🎤 Using with Emotion

##### 🚩 Installation ```sh npm install @emotion/{styled,react} # or yarn add @emotion/{styled,react} ```
`theme/emotion.d.ts` ```ts import '@emotion/react'; import { AppThemeType } from './index'; declare module '@emotion/react' { export interface Theme extends AppThemeType {} } ```

### 🚀 Integration into Your App
`app.tsx` ```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 = () => ( ); ```
## Media queries API 🚀 All media query functions cache their results to improve performance.
### Min-width - `up` ```tsx const Box = styled.div` display: none; ${({ theme }) => theme.breakpoints.up('sm')} { display: block; } `; ```
Will be converted to CSS: ```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):
```tsx const Box = styled.div` display: block; ${({ theme }) => theme.breakpoints.down('md')} { display: none; } `; ```
Will be converted to CSS: ```css @media (max-width: 767.98px) { display: none; } ```
> Why subtract .02px? Browsers don’t currently support [range context queries](https://www.w3.org/TR/mediaqueries-4/#range-context), so we work around the limitations of [min- and max- prefixes](https://www.w3.org/TR/mediaqueries-4/#mq-min-max) 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.
```tsx const Box = styled.div` background-color: pink; ${({ theme }) => theme.breakpoints.only('md')} { background-color: rebeccapurple; } `; ```
Will be converted to CSS: ```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.
```tsx const Box = styled.div` background-color: gold; ${({ theme }) => theme.breakpoints.between('md', 'xl')} { background-color: rebeccapurple; } `; ```
Will be converted to CSS: ```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
```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 theme = useTheme(); const isMd = useMediaQuery(theme.breakpoints.only('md')); return {isMd && }; }; ``` ### API #### Type Declarations ```ts 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](https://github.com/mg901/styled-breakpoints/blob/master/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} 🐛