{"id":15386,"library":"styled-components-breakpoint","title":"Styled Components Breakpoint Utilities","description":"styled-components-breakpoint provides utility functions for integrating responsive design breakpoints directly into styled-components using CSS-in-JS. Currently in a 3.0.0-preview.20 release, it offers two primary modes of operation: themeable mixins that leverage styled-components' ThemeProvider to define breakpoints globally, and static mixin factories for scenarios where breakpoints do not need to be dynamic or themed. The library simplifies the creation of media queries, allowing developers to define styles that adapt across different screen sizes (e.g., mobile, tablet, desktop) using an intuitive API like breakpoint('md'). It is designed to complement other related packages such as styled-components-spacing and styled-components-grid, promoting a consistent approach to responsive layouts within styled-components projects. While a formal release cadence isn't specified, its preview status indicates ongoing development towards a stable v3.","status":"active","version":"3.0.0-preview.20","language":"javascript","source_language":"en","source_url":"https://github.com/jameslnewell/styled-components-breakpoint","tags":["javascript","react","styled-components","breakpoint","breakpoints","media","style","tablet","desktop","typescript"],"install":[{"cmd":"npm install styled-components-breakpoint","lang":"bash","label":"npm"},{"cmd":"yarn add styled-components-breakpoint","lang":"bash","label":"yarn"},{"cmd":"pnpm add styled-components-breakpoint","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core styling library required for this utility. Note that peer dependency specifies '>=1 <=4', which is an older range. Modern styled-components (v5, v6) are generally compatible, but thorough testing is advised.","package":"styled-components","optional":false},{"reason":"TypeScript type definitions for styled-components, necessary for defining custom themes and leveraging type-safe theme properties.","package":"@types/styled-components","optional":true}],"imports":[{"note":"Primary default export for theme-driven media queries. This package primarily uses ESM.","wrong":"const breakpoint = require('styled-components-breakpoint');","symbol":"breakpoint","correct":"import breakpoint from 'styled-components-breakpoint';"},{"note":"Named export for theme-driven value mapping. Always use named import.","wrong":"const { map } = require('styled-components-breakpoint');","symbol":"map","correct":"import { map } from 'styled-components-breakpoint';"},{"note":"Named exports for creating static breakpoint utilities without relying on a ThemeProvider.","wrong":"const { createBreakpoint, createMap } = require('styled-components-breakpoint');","symbol":"createBreakpoint, createMap","correct":"import { createBreakpoint, createMap } from 'styled-components-breakpoint';"},{"note":"For TypeScript users, it is crucial to augment styled-components' DefaultTheme to include the 'breakpoints' property, ensuring type safety when accessing theme values.","symbol":"DefaultTheme (TypeScript augmentation)","correct":"import { DefaultTheme } from 'styled-components';\n\ndeclare module 'styled-components' {\n export interface DefaultTheme {\n breakpoints: {\n [name: string]: number;\n };\n }\n}"}],"quickstart":{"code":"import React from 'react';\nimport ReactDOM from 'react-dom/client';\nimport styled, { ThemeProvider } from 'styled-components';\nimport breakpoint, { map } from 'styled-components-breakpoint';\n\n// Define a theme with custom breakpoints\nconst theme = {\n breakpoints: {\n xs: 0,\n sm: 576,\n md: 768,\n lg: 992,\n xl: 1200,\n },\n};\n\n// Define a styled component using the breakpoint and map utilities\nconst ResponsiveBox = styled.div`\n padding: 1rem;\n text-align: center;\n font-family: sans-serif;\n \n // Base style for all sizes\n background-color: lightblue;\n color: black;\n font-size: 14px;\n\n // Styles from 'md' breakpoint onwards\n ${breakpoint('md')`\n background-color: lightgreen;\n font-size: 18px;\n padding: 2rem;\n `}\n\n // Styles from 'lg' breakpoint onwards\n ${breakpoint('lg')`\n background-color: lightcoral;\n font-size: 22px;\n padding: 3rem;\n `}\n\n // Map colors based on breakpoints\n ${map(\n { xs: 'crimson', sm: 'darkblue', md: 'purple', lg: 'darkgreen', xl: 'black' },\n color => `color: ${color};`\n )}\n`;\n\nfunction App() {\n return (\n \n \n
Responsive Text Example
\n
\n This box changes its background color, font size, padding, and text color\n based on the viewport width using styled-components-breakpoint.\n
\n
Try resizing your browser window!
\n \n \n );\n}\n\nconst root = ReactDOM.createRoot(document.getElementById('root') ?? document.createElement('div'));\nroot.render();\n","lang":"typescript","description":"Demonstrates how to set up `styled-components-breakpoint` with a `ThemeProvider` for custom breakpoints, applying responsive styles using the `breakpoint` mixin and mapping values with the `map` mixin."},"warnings":[{"fix":"Monitor the official GitHub repository and changelog for stable releases and migration guides. Consider using v2 if stability is paramount.","message":"Version 3.0.0-preview.20 is a pre-release version. APIs might change before the stable v3 release, and it may contain unresolved bugs. Use in production with caution.","severity":"breaking","affected_versions":"3.0.0-preview.x"},{"fix":"Thoroughly test `styled-components-breakpoint` with your specific `styled-components` version. Consider opening an issue on the GitHub repo if compatibility problems arise with newer styled-components versions not covered by the peer dependency.","message":"The package's peer dependency for 'styled-components' is specified as '>= 1 <= 4'. While it might function with newer versions (like v5 or v6), this broad and outdated range does not guarantee full compatibility or support for all features of the latest styled-components versions. Potential unexpected behavior or missing functionality may arise.","severity":"gotcha","affected_versions":">=3.0.0-preview"},{"fix":"Create a `styled.d.ts` file (or similar) and use declaration merging:\n`import 'styled-components'; declare module 'styled-components' { export interface DefaultTheme { breakpoints: { [name: string]: number; }; } }`","message":"For TypeScript users, it is essential to augment the `styled-components` `DefaultTheme` interface to include the `breakpoints` property. Failure to do so will result in TypeScript errors when accessing theme properties or using the `breakpoint` and `map` utilities.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Wrap your component tree with `ThemeProvider` and pass a `theme` object containing a `breakpoints` property:\n`import { ThemeProvider } from 'styled-components'; const theme = { breakpoints: { ... } }; ...`","cause":"The `breakpoints` object is not defined in the `styled-components` theme when using the default `breakpoint` or `map` utilities.","error":"TypeError: Cannot read properties of undefined (reading 'breakpoints')"},{"fix":"Augment the `DefaultTheme` interface in a declaration file (e.g., `styled.d.ts`):\n`import 'styled-components'; declare module 'styled-components' { export interface DefaultTheme { breakpoints: { [name: string]: number; }; } }`","cause":"In TypeScript, the `DefaultTheme` interface has not been augmented to include the `breakpoints` property.","error":"Property 'breakpoints' does not exist on type 'DefaultTheme'."},{"fix":"Switch to ESM `import` statements:\n`import breakpoint, { map } from 'styled-components-breakpoint';`","cause":"Attempting to use CommonJS `require()` syntax in an ESM-only context for `styled-components-breakpoint`.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}