styled-components-breakpoint
Version:
Utility functions for creating breakpoints in `styled-components` 💅.
275 lines (194 loc) • 6.83 kB
Markdown
# styled-components-breakpoint
   [![Build Status]](https://github.com/jameslnewell/styled-components-breakpoint/actions)
Utility functions for creating breakpoints in `styled-components` 💅.
> 🕸 [Website](https://jameslnewell.github.io/styled-components-breakpoint/)
> 📘 [Change log](https://github.com/jameslnewell/styled-components-breakpoint/blob/master/CHANGELOG.md)
> 👀 Have a look at [`styled-components-spacing`](https://github.com/jameslnewell/styled-components-spacing) and [`styled-components-grid`](https://github.com/jameslnewell/styled-components-grid) which both work well with this package.
## Installation
NPM:
```
npm install styled-components-breakpoint
```
Yarn:
```bash
yarn add styled-components-breakpoint
```
## Usage
### Using the themable mixins
```jsx
import styled from 'styled-components';
import breakpoint, {map} from 'styled-components-breakpoint';
const Heading = styled.h1`
color: #444;
font-family: sans-serif;
font-size: 12px;
${breakpoint('md')`
font-size: 16px;
`}
${breakpoint('xl')`
font-size: 24px;
`}
${map({mobile: 'red', desktop: 'green'}, color => `color: ${color};`)}
`;
```
### Using custom breakpoints for the themable mixins
The themable breakpoints can be customised using `ThemeProvider`. For example, to use the same breakpoints as [Bootstrap](https://getbootstrap.com/docs/4.0/layout/overview/#responsive-breakpoints), you can do so like this:
```jsx
import React from 'react';
import ReactDOM from 'react-dom';
import {ThemeProvider} from 'styled-components';
const theme = {
breakpoints: {
xs: 0,
sm: 576,
md: 768,
lg: 992,
xl: 1200,
},
};
ReactDOM.render(
<ThemeProvider theme={theme}>{/* ... */}</ThemeProvider>,
document.getElementById('app'),
);
```
If you're using Typescript, you'll also need to define the breakpoints and spacings on the theme.
`styled.d.ts`
```tsx
import {DefaultTheme} from 'styled-components';
declare module 'styled-components' {
export interface DefaultTheme {
breakpoints: {
[name in 'xs' | 'sm' | 'md' | 'lg' | 'xl']: number;
};
}
}
```
### Using the mixin factories
If your breakpoints and spacings don't need to be themable then you can use the static mixin factories.
`breakpoints.js`: Configure the breakpoints
```jsx
import styled from 'styled-components';
import {createBreakpoint, createMap} from 'styled-components-breakpoint';
const breakpoints = {
xs: 0,
sm: 576,
md: 768,
lg: 992,
xl: 1200,
};
const breakpoint = createBreakpoint(breakpoints);
const map = createMap(breakpoints);
const Heading = styled.h1`
color: #444;
font-family: sans-serif;
font-size: 12px;
${breakpoint('md')`
font-size: 16px;
`}
${breakpoint('xl')`
font-size: 24px;
`}
${map({md: 'red', xl: 'green'}, color => `color: ${color};`)}
`;
```
## API
### breakpoint(a, b)
Generate a media query using using the set of breakpoints defined in the theme.
**Parameters:**
- `a` - Required - The breakpoint name at which the style applies.
- `b` - Optional - The breakpoint name at which the style stops applying.
**Example:**
```jsx
import styled from 'styled-components';
import breakpoint from 'styled-components-breakpoint';
export const Heading = styled.h1`
font-size: 12px;
${breakpoint('tablet')`
font-size: 16px;
`}
${breakpoint('desktop')`
font-size: 24px;
`}
`;
// font-size will increase/decrease with the window size
<Heading>The quick brown fox jumps over the lazy dog</Heading>;
```
### map(valueOrValues, mapValueToStyle)
Map a set of values to a set of media queries using the set of breakpoints defined in the theme.
**Parameters:**
- `valueOrValues` - Required - The value or a map of values to style at each breakpoint.
- `mapValueToStyle` - Required - The function used to map a value to style.
**Example:**
```jsx
import styled from 'styled-components';
import {map} from 'styled-components-breakpoint';
const sizes = {
sm: '12px',
md: '16px',
lg: '20px',
}
const fontSize = ({size}) => map(size, s => `font-size: ${sizes[s]};`);
export const Heading = styled.h1`
${fontSize}
`;
// font-size will always remain the same size
<Heading size="sm">The quick brown fox jumps over the lazy dog</Heading>
// font-size will increase/decrease with the window size
<Heading size={{mobile: 'sm', tablet: 'lg'}}>The quick brown fox jumps over the lazy dog</Heading>
```
### createBreakpoint(breakpoints)
Create a `breakpoint(a, b)` function to generate a media query using a set of pre-defined breakpoints.
**Parameters:**
- `breakpoints` - Required - A set of breakpoints.
**Example:**
```js
import {createBreakpoint} from 'styled-components-breakpoint';
export const breakpoint = createBreakpoint({
xs: 0,
sm: 300,
md: 600,
lg: 900,
xl: 1200,
});
```
### createMap(breakpoints)
Create a `map(valueOrValues, mapValueToStyle)` function to map a set of values to a set of media queries using a set of pre-defined breakpoints.
**Parameters:**
- `breakpoints` - Required - A set of breakpoints.
**Example:**
```js
import {createMap} from 'styled-components-breakpoint';
export const map = createMap({
xs: 0,
sm: 300,
md: 600,
lg: 900,
xl: 1200,
});
```
## Default breakpoints
If you don't provide any breakpoints, the default breakpoints used by the `breakpoint()` and `map()` functions are:
| Breakpoint | Size | Description |
| ---------- | ---------------------- | ------------------------------------------------------------------------------------------- |
| `mobile` | `0px` (`0em`) | Targeting all devices |
| `tablet` | `737px` (`46.0625em`) | Targeting devices that are LARGER than the iPhone 6 Plus (which is 736px in landscape mode) |
| `desktop` | `1195px` (`74.6875em`) | Targeting devices that are LARGER than the 11" iPad Pro (which is 1194px in landscape mode) |
## FAQ
### Q. How do I use CSS objects?
```jsx
import styled from 'styled-components';
import breakpoint from 'styled-components-breakpoint';
const RainbowButton = styled.button(
{
color: 'white',
backgroundColor: 'red',
},
breakpoint('tablet')({
backgroundColor: 'blue',
}),
breakpoint('desktop')({
backgroundColor: 'green',
}),
);
<RainbowButton>I am RGB!</RainbowButton>;
```