Skip to content

mg901/styled-breakpoints

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation


styled-breakpoints
GitHub Workflow Status coverage status npm bundle size npm downloads npm version

Simple and powerful tool for creating media queries with SSR support.

Styled Components Logo Β Β Β Β ORΒ Β Β  Emotion logo



🌼 Preview

Inside components.

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.

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

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

  return <>{isMd && <Box />}</>;
};

Examples

πŸ‘‰πŸ» Mobile First

From smallest to largest


πŸ‘‰πŸ» Desktop First

From largest to smallest


πŸ‘‰πŸ» Hooks API



πŸ“– Documentation


🧐 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

🚩 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 = {
  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

import { createStyledBreakpointsTheme } from 'styled-breakpoints';

export const theme = createStyledBreakpointsTheme();


Customization

🚩 Breakpoints

theme/index.ts

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

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(),
};


πŸ’… Using with Styled Components

🚩 Installation
npm install styled-components

# or

yarn add styled-components

theme/styled.d.ts

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

type ThemeConfig = typeof theme;

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


πŸ‘©β€πŸŽ€ Using with Emotion

🚩 Installation
npm install @emotion/{styled,react}

# or

yarn add @emotion/{styled,react}

theme/emotion.d.ts

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

type ThemeConfig = typeof theme;

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


πŸš€ Integration to Your App


app.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 = () => (
  <ThemeProvider theme={theme}>
    <Box />
  </ThemeProvider>
);

Media queries API

πŸš€ Caching is implemented in all functions to optimize performance.


πŸ‘‰πŸ» Min-width - up

const Box = styled.div`
  display: none;

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

Will convert to vanilla css:
@media (min-width: 768px) {
  display: block;
}


πŸ‘‰πŸ» Max-width - down

We occasionally use media queries that go in the other direction (the given screen size or smaller):


const Box = styled.div`
  display: block;

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

Will convert to vanilla 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 are also media queries and mixins for targeting 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 convert to vanilla css:
@media (min-width: 768px) and (max-width: 991.98px) {
  background-color: rebeccapurple;
}


πŸ‘‰πŸ» Breakpoints range - between

Similarly, media queries may span multiple breakpoint widths.


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

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

Will convert to vanilla 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 284b.

Type declaration
 declare function useMediaQuery(query: string) => boolean
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 <AnotherComponent>{isMd && <Box />}</AnotherComponent>;
};


License

MIT License

Copyright (c) 2018-2024 Maxim Alyoshin.

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



Contributors

mg901
mg901

πŸ’¬ πŸ’» 🎨 πŸ“– πŸ’‘ πŸš‡ 🚧 πŸ“† πŸ“£ πŸ”¬ πŸ‘€ ⚠️ πŸ”§ βœ…
Abu Shamsutdinov
Abu Shamsutdinov

πŸ› πŸ’» πŸ’‘ πŸ€” πŸ‘€ πŸ“’
Sova
Sova

πŸ’» πŸ’‘ πŸ€” πŸ‘€ πŸ“’
Jussi Kinnula
Jussi Kinnula

πŸ› πŸ’»
RafaΕ‚ Wyszomirski
RafaΕ‚ Wyszomirski

πŸ“–
Adrian CelczyΕ„ski
Adrian CelczyΕ„ski

πŸ› πŸ’»
Sam Holmes
Sam Holmes

πŸ’» πŸ€”
Ontopic
Ontopic

πŸ€”
Ryan Bell
Ryan Bell

πŸ€”
Bart Nagel
Bart Nagel

πŸ› πŸ’» πŸ’‘ πŸ€”
Greg McKelvey
Greg McKelvey

πŸ’»
Buck DeFore
Buck DeFore

πŸ€”
Pierre Burel
Pierre Burel

πŸ›
Pawel Kochanek
Pawel Kochanek

πŸ› πŸ’»
Ian Christopher B. de Jesus
Ian Christopher B. de Jesus

πŸ›
David de Lusenet
David de Lusenet

πŸ› πŸ€”
Dan Adler
Dan Adler

πŸ›