Styled Components Breakpoint Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'breakpoints')

  cause The `breakpoints` object is not defined in the `styled-components` theme when using the default `breakpoint` or `map` utilities.
  fix Wrap your component tree with `ThemeProvider` and pass a `theme` object containing a `breakpoints` property: `import { ThemeProvider } from 'styled-components'; const theme = { breakpoints: { ... } }; <ThemeProvider theme={theme}>...</ThemeProvider>`

• Property 'breakpoints' does not exist on type 'DefaultTheme'.

  cause In TypeScript, the `DefaultTheme` interface has not been augmented to include the `breakpoints` property.
  fix Augment the `DefaultTheme` interface in a declaration file (e.g., `styled.d.ts`): `import 'styled-components'; declare module 'styled-components' { export interface DefaultTheme { breakpoints: { [name: string]: number; }; } }`

• ReferenceError: require is not defined

  cause Attempting to use CommonJS `require()` syntax in an ESM-only context for `styled-components-breakpoint`.
  fix Switch to ESM `import` statements: `import breakpoint, { map } from 'styled-components-breakpoint';`

Warnings

• breaking 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.
  Fix: Monitor the official GitHub repository and changelog for stable releases and migration guides. Consider using v2 if stability is paramount.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Create a `styled.d.ts` file (or similar) and use declaration merging: `import 'styled-components'; declare module 'styled-components' { export interface DefaultTheme { breakpoints: { [name: string]: number; }; } }`

Install

• npm install styled-components-breakpoint npm
• yarn add styled-components-breakpoint yarn
• pnpm add styled-components-breakpoint pnpm

Imports

• breakpoint
  wrong:

  const breakpoint = require('styled-components-breakpoint');

  correct:

  import breakpoint from 'styled-components-breakpoint';

  Primary default export for theme-driven media queries. This package primarily uses ESM.
• map
  wrong:

  const { map } = require('styled-components-breakpoint');

  correct:

  import { map } from 'styled-components-breakpoint';

  Named export for theme-driven value mapping. Always use named import.
• createBreakpoint, createMap
  wrong:

  const { createBreakpoint, createMap } = require('styled-components-breakpoint');

  correct:

  import { createBreakpoint, createMap } from 'styled-components-breakpoint';

  Named exports for creating static breakpoint utilities without relying on a ThemeProvider.
• DefaultTheme (TypeScript augmentation)

  import { DefaultTheme } from 'styled-components';
  
  declare module 'styled-components' {
    export interface DefaultTheme {
      breakpoints: {
        [name: string]: number;
      };
    }
  }

  For TypeScript users, it is crucial to augment styled-components' DefaultTheme to include the 'breakpoints' property, ensuring type safety when accessing theme values.

Quickstart

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.

import React from 'react';
import ReactDOM from 'react-dom/client';
import styled, { ThemeProvider } from 'styled-components';
import breakpoint, { map } from 'styled-components-breakpoint';

// Define a theme with custom breakpoints
const theme = {
  breakpoints: {
    xs: 0,
    sm: 576,
    md: 768,
    lg: 992,
    xl: 1200,
  },
};

// Define a styled component using the breakpoint and map utilities
const ResponsiveBox = styled.div`
  padding: 1rem;
  text-align: center;
  font-family: sans-serif;
  
  // Base style for all sizes
  background-color: lightblue;
  color: black;
  font-size: 14px;

  // Styles from 'md' breakpoint onwards
  ${breakpoint('md')`
    background-color: lightgreen;
    font-size: 18px;
    padding: 2rem;
  `}

  // Styles from 'lg' breakpoint onwards
  ${breakpoint('lg')`
    background-color: lightcoral;
    font-size: 22px;
    padding: 3rem;
  `}

  // Map colors based on breakpoints
  ${map(
    { xs: 'crimson', sm: 'darkblue', md: 'purple', lg: 'darkgreen', xl: 'black' },
    color => `color: ${color};`
  )}
`;

function App() {
  return (
    <ThemeProvider theme={theme}>
      <ResponsiveBox>
        <h1>Responsive Text Example</h1>
        <p>
          This box changes its background color, font size, padding, and text color
          based on the viewport width using styled-components-breakpoint.
        </p>
        <p>Try resizing your browser window!</p>
      </ResponsiveBox>
    </ThemeProvider>
  );
}

const root = ReactDOM.createRoot(document.getElementById('root') ?? document.createElement('div'));
root.render(<App />);