styled-system
Advanced tools
Comparing version 1.1.3 to 1.1.4
{ | ||
"name": "styled-system", | ||
"version": "1.1.3", | ||
"version": "1.1.4", | ||
"description": "Design system utilities for styled-components, glamorous, and other css-in-js libraries", | ||
@@ -24,3 +24,3 @@ "main": "dist/index.js", | ||
"devDependencies": { | ||
"ava": "^0.19.1", | ||
"ava": "^0.25.0", | ||
"babel-cli": "^6.24.1", | ||
@@ -31,5 +31,6 @@ "babel-core": "^6.25.0", | ||
"babel-preset-react": "^6.24.1", | ||
"babel-preset-stage-0": "^6.24.1", | ||
"babel-register": "^6.24.1", | ||
"benchmark": "^2.1.4", | ||
"bundlesize": "^0.13.2", | ||
"bundlesize": "^0.16.0", | ||
"codecov": "^2.2.0", | ||
@@ -41,8 +42,8 @@ "funcup": "^1.0.0-0", | ||
"palx": "^1.0.2", | ||
"react": "^15.6.0", | ||
"react-dom": "^15.6.0", | ||
"react": "^16.2.0", | ||
"react-dom": "^16.2.0", | ||
"react-live": "^1.6.1", | ||
"react-test-renderer": "^15.5.4", | ||
"react-test-renderer": "^16.2.0", | ||
"react-x-ray": "^1.0.0-2", | ||
"styled-components": "^2.1.0", | ||
"styled-components": "^3.1.6", | ||
"webpack": "^2.6.1", | ||
@@ -49,0 +50,0 @@ "webpack-dev-server": "^2.4.5" |
707
README.md
@@ -27,2 +27,3 @@ # styled-system | ||
- Works with most css-in-js libraries, including [styled-components][sc], [glamorous][glamorous], [emotion][emotion], [fela][fela], and [cxs][cxs] | ||
- Used in [Rebass](http://jxnblk.com/rebass), [Grid Styled](http://jxnblk.com/grid-styled/), and the [Priceline Design System](https://github.com/pricelinelabs/design-system) | ||
@@ -32,10 +33,22 @@ > "The future of css-in-js is going to look something like styled-system with its responsive values."<br/> | ||
> "Fantastic set of tools that offer the ease and API of tachyons/functional CSS but, are way more customisable." | ||
> – [Varun Vachhar](https://mobile.twitter.com/winkerVSbecks/status/955619873463431168) | ||
> "Coming from @tachyons_css, the styled-system utilities from @jxnblk is the missing link I’ve been looking for."<br/> | ||
> – [Nathan Young](https://mobile.twitter.com/nathanyoung/status/891353221880360960) | ||
### Table of Contents | ||
- [Usage](#usage) | ||
- [Getting Started](#getting-started) | ||
- [How it Works](#how-it-works) | ||
- [Responsive Styles](#responsive-styles) | ||
- [API](#api) | ||
- [Default Theme](#default-theme) | ||
- [Related](#related) | ||
## Usage | ||
```jsx | ||
// Example uses styled-components, | ||
// but styled-system works with most other css-in-js libraries as well | ||
// Example uses styled-components, but styled-system works with most other css-in-js libraries as well | ||
import styled from 'styled-components' | ||
@@ -60,9 +73,9 @@ import { space, width, fontSize, color } from 'styled-system' | ||
// font-size: 20px | ||
// font-size: 20px (theme.fontSizes[4]) | ||
<Box fontSize={4} /> | ||
// margin: 16px | ||
// margin: 16px (theme.space[2]) | ||
<Box m={2} /> | ||
// padding: 32px | ||
// padding: 32px (theme.space[3]) | ||
<Box p={3} /> | ||
@@ -72,2 +85,4 @@ | ||
<Box color='tomato' /> | ||
// color: #333 (theme.colors.gray[0]) | ||
<Box color='grays.0' /> | ||
@@ -81,5 +96,4 @@ | ||
Set responsive width, margin, padding, font-size, | ||
and other properties with a shorthand | ||
array syntax. [Read more](#responsive-styles) | ||
Set responsive width, margin, padding, font-size, and other properties with a shorthand array syntax. | ||
[Read more](#responsive-styles) | ||
@@ -100,2 +114,264 @@ ```jsx | ||
## Getting Started | ||
Although it's not required, styled-system works best with a theme that's tailored to your own custom styles. | ||
Create a `theme.js` file that exports an object and add a [ThemeProvider](https://www.styled-components.com/docs/advanced#theming) | ||
to the root of your application. | ||
```js | ||
// empty theme.js | ||
const theme = {} | ||
export default theme | ||
``` | ||
```jsx | ||
// root App component | ||
import React from 'react' | ||
import { ThemeProvider } from 'styled-components' | ||
import theme from './theme' | ||
const App = props => ( | ||
<ThemeProvider theme={theme}> | ||
{/* ... */} | ||
</ThemeProvider> | ||
) | ||
``` | ||
Most utility functions in styled-system will attempt to find a value from your theme first, | ||
then fallback to a hard-coded value if it hasn't been defined in your theme. | ||
For example, defining a `colors` object can make using a common color palette across your app simpler. | ||
```js | ||
// theme.js | ||
const colors = { | ||
text: '#024', | ||
blue: '#07c' | ||
} | ||
const theme = { | ||
colors | ||
} | ||
export default theme | ||
``` | ||
With a component that uses the `color` function from styled-system, the name of the color defined in your theme can be used as a prop. | ||
```jsx | ||
// picks up the value `#07c` from the theme | ||
<Box color='blue' /> | ||
``` | ||
When a value is passed that's **not** in the theme, it will be passed as a raw value. | ||
```jsx | ||
// renders the CSS `tomato` color since it's not defined in theme | ||
<Box color='tomato' /> | ||
``` | ||
It's recommended to add objects and array scales to your theme to ensure consistent, constraint-based values are used throughout your app. | ||
All theme values are optional, so use your own discretion when creating a theme. | ||
See the [Default Theme](#default-theme) section for a reference to the default fallback values. | ||
```js | ||
// theme.js | ||
// breakpoint values | ||
// any array length works with styled-system | ||
const breakpoints = [ | ||
'40em', '52em', '64em' | ||
] | ||
const colors = { | ||
text: '#024', | ||
blue: '#07c', | ||
// nested objects work as well | ||
dark: { | ||
blue: '#058' | ||
}, | ||
// arrays can be used for scales of colors | ||
gray: [ | ||
'#333', | ||
'#666', | ||
'#999', | ||
'#ccc', | ||
'#eee', | ||
'#f6f6f6', | ||
] | ||
} | ||
// space is used for margin and padding scales | ||
// it's recommended to use powers of two to ensure alignment | ||
// when used in nested elements | ||
// numbers are converted to px | ||
const space = [ | ||
0, 4, 8, 16, 32, 64, 128, 256, 512 | ||
] | ||
// typographic scale | ||
const fontSizes = [ | ||
12, 14, 16, 20, 24, 32, 48, 64, 96, 128 | ||
] | ||
// for any scale, either array or objects will work | ||
const lineHeights = [ | ||
1, 1.125, 1.25, 1.5 | ||
] | ||
const fontWeights = { | ||
normal: 500, | ||
bold: 700 | ||
} | ||
const letterSpacings = { | ||
normal: 'normal', | ||
caps: '0.25em' | ||
} | ||
// border-radius | ||
const radii = [ | ||
0, 2, 4, 8 | ||
] | ||
const borderWidths = [ | ||
0, 1, 2 | ||
] | ||
const shadows = [ | ||
`0 1px 2px 0 ${colors.text}`, | ||
`0 1px 4px 0 ${colors.text}` | ||
] | ||
const theme = { | ||
breakpoints, | ||
colors, | ||
space, | ||
fontSizes, | ||
lineHeights, | ||
fontWeights, | ||
letterSpacings, | ||
radii, | ||
borderWidths, | ||
shadows, | ||
} | ||
export default theme | ||
``` | ||
Next, create a set of UI components that provide convenient style props to the values defined in the theme. | ||
It's recommended to keep components simple and focused on doing one thing well. | ||
For UI components, it's common to separate them according to different concerns, such as layout, typography, and other styles. | ||
However, there may be some general purpose style props that you'd like to apply consistently across your entire component set, such as margin, padding, and color. | ||
```js | ||
import styled from 'styled-components' | ||
import { | ||
space, | ||
color, | ||
width, | ||
fontSize, | ||
fontWeight, | ||
textAlign, | ||
lineHeight | ||
} from 'styled-system' | ||
// Example of a general purpose Box layout component | ||
export const Box = styled.div` | ||
${space} | ||
${color} | ||
${width} | ||
` | ||
// General purpose typographic component | ||
export const Text = styled.div` | ||
${space} | ||
${color} | ||
${fontSize} | ||
${fontWeight} | ||
${textAlign} | ||
${lineHeight} | ||
` | ||
``` | ||
## How it Works | ||
Most CSS-in-JS libraries accept functions as arguments to create dynamic styles based on props. | ||
For example, the following sets color dynamically in styled-components based on the `color` prop: | ||
```js | ||
import styled from 'styled-components' | ||
const Box = styled.div` | ||
color: ${props => props.color}; | ||
` | ||
``` | ||
Beyond just passing a dynamic value, an entire style declaration can be returned in functions like this. | ||
```js | ||
import styled from 'styled-components' | ||
const getColor = props => `color: ${props.color};` | ||
const Box = styled.div` | ||
${getColor} | ||
` | ||
``` | ||
Style object can also be returned, which is a much simpler way to handle dynamic values in JavaScript. | ||
```js | ||
import styled from 'styled-components' | ||
// works exactly the same as the previous function | ||
const getColor = props => ({ | ||
color: props.color | ||
}) | ||
const Box = styled.div` | ||
${getColor} | ||
` | ||
``` | ||
By using style objects instead of embedded CSS strings, styled-system is compatible with other libraries, | ||
such as [glamorous][glamorous] and [emotion][emotion]. | ||
The core utilities in styled-system are built on this pattern and consist of functions that take `props` as an argument | ||
and return style objects, | ||
while making it simpler to use values from a theme and apply styles responsively across breakpoints. | ||
These style functions can be written on a one-off basis, but styled-system is meant to help reduce boilerplate, ensure a consistent styling API, and speed the development of React-based design systems. | ||
## Responsive Styles | ||
Often when working on responsive layouts, it's useful to adjust styles across a singular dimension – | ||
such as font-size, margin, padding, and width. | ||
Instead of manually managing media queries and adding nested style objects throughout a code base, | ||
styled-system offers a convenient shorthand syntax for adding responsive styles with a mobile-first approach. | ||
While this syntax can seem odd at first, it can become a powerful way to manage responsive typography and layouts. | ||
All core props accept arrays as values for mobile-first responsive styles. | ||
```jsx | ||
<Box | ||
width={[ | ||
1, // 100% below the smallest breakpoint | ||
1/2, // 50% from the next breakpoint and up | ||
1/4 // 25% from the next breakpoint and up | ||
]} | ||
/> | ||
// responsive font size | ||
<Box fontSize={[ 1, 2, 3, 4 ]} /> | ||
// responsive margin | ||
<Box m={[ 1, 2, 3, 4 ]} /> | ||
// responsive padding | ||
<Box p={[ 1, 2, 3, 4 ]} /> | ||
``` | ||
## API | ||
@@ -108,3 +384,2 @@ | ||
- [color](#color-responsive) (and background-color) | ||
- [Responsive Styles](#responsive-styles) | ||
- [**Extras**](#extras) | ||
@@ -125,2 +400,3 @@ - [textAlign](#textalign-responsive) | ||
- [boxShadow](#boxshadow) | ||
- [**Pseudo-classes**](#pseudo-classes) | ||
- [hover](#hover) | ||
@@ -130,2 +406,3 @@ - [focus](#focus) | ||
- [disabled](#disabled) | ||
- [**Table of Style Props**](#table-of-style-props) | ||
- [**Utilities**](#utilities) | ||
@@ -150,8 +427,9 @@ - [theme](#theme) | ||
The space utility converts shorthand margin and padding props to margin and padding CSS declarations. | ||
Numbers from 0-4 are converted to values on the [spacing scale](#spacing-scale). | ||
Negative values can be used for negative margins. | ||
Numbers greater than 4 are converted to raw pixel values. | ||
String values are passed as raw CSS values. | ||
And array values are converted into [responsive values](#responsive-styles). | ||
- Numbers from 0-4 (or the length of `theme.space`) are converted to values on the [spacing scale](#spacing-scale). | ||
- Negative values can be used for negative margins. | ||
- Numbers greater than the length of the `theme.space` array are converted to raw pixel values. | ||
- String values are passed as raw CSS values. | ||
- And array values are converted into [responsive values](#responsive-styles). | ||
Margin and padding props follow a shorthand syntax for specifying direction. | ||
@@ -174,2 +452,21 @@ | ||
```jsx | ||
// examples (margin prop) | ||
// sets margin value of `theme.space[2]` | ||
<Box m={2} /> | ||
// sets margin value of `-1 * theme.space[2]` | ||
<Box m={-2} /> | ||
// sets a margin value of `16px` since it's greater than `theme.space.length` | ||
<Box m={16} /> | ||
// sets margin `'auto'` | ||
<Box m='auto' /> | ||
// sets margin `8px` on all viewports and `16px` from the smallest breakpoint and up | ||
<Box m={[ 1, 2 ]} /> | ||
``` | ||
### width (responsive) | ||
@@ -188,2 +485,18 @@ | ||
```jsx | ||
// examples | ||
// width `50%` | ||
<Box width={1/2} /> | ||
// width `256px` | ||
<Box width={256} /> | ||
// width `'2em'` | ||
<Box width='2em' /> | ||
// width `100%` on all viewports and `50%` from the smallest breakpoint and up | ||
<Box width={[ 1, 1/2 ]} /> | ||
``` | ||
### fontSize (responsive) | ||
@@ -196,7 +509,24 @@ | ||
The fontSize utility parses a component's `fontSize` prop and converts it into a CSS font-size declaration. | ||
Numbers from 0-8 are converted to values on the [font size scale](#font-size-scale). | ||
Numbers greater than 8 are converted to raw pixel values. | ||
String values are passed as raw CSS values. | ||
And array values are converted into [responsive values](#responsive-styles). | ||
- Numbers from 0-8 (or `theme.fontSizes.length`) are converted to values on the [font size scale](#font-size-scale). | ||
- Numbers greater than `theme.fontSizes.length` are converted to raw pixel values. | ||
- String values are passed as raw CSS values. | ||
- And array values are converted into [responsive values](#responsive-styles). | ||
```jsx | ||
// examples | ||
// font-size of `theme.fontSizes[3]` | ||
<Text fontSize={3} /> | ||
// font-size `32px` | ||
<Text fontSize={32} /> | ||
// font-size `'2em'` | ||
<Text fontSize='2em' /> | ||
// font-size `10px` on all viewports and `12px` from the smallest breakpoint and up | ||
<Text fontSize={[ 10, 12 ]} /> | ||
``` | ||
### color (responsive) | ||
@@ -213,25 +543,14 @@ | ||
--- | ||
### Responsive Styles | ||
All core function props accept arrays as values for mobile-first responsive styles. | ||
```jsx | ||
<Box | ||
width={[ | ||
1, // 100% below the smallest breakpoint | ||
1/2, // 50% from the next breakpoint and up | ||
1/4 // 25% from the next breakpoint and up | ||
]} | ||
/> | ||
// examples | ||
// responsive font size | ||
<Box fontSize={[ 1, 2, 3, 4 ]} /> | ||
// picks the value defined in `theme.colors['blue']` | ||
<Box color='blue' /> | ||
// responsive margin | ||
<Box m={[ 1, 2, 3, 4 ]} /> | ||
// picks up a nested color value using dot notation | ||
// `theme.colors['gray'][0]` | ||
<Box color='gray.0' /> | ||
// responsive padding | ||
<Box p={[ 1, 2, 3, 4 ]} /> | ||
// raw CSS color value | ||
<Box color='#f00' /> | ||
``` | ||
@@ -250,5 +569,8 @@ | ||
import { textAlign } from 'styled-system' | ||
// <Text align='center' /> | ||
``` | ||
```jsx | ||
<Text align='center' /> | ||
``` | ||
### lineHeight | ||
@@ -258,3 +580,6 @@ | ||
import { lineHeight } from 'styled-system' | ||
// <Text lineHeight={1} /> | ||
``` | ||
```jsx | ||
<Text lineHeight={1} /> | ||
// props.theme.lineHeights[1] | ||
@@ -267,3 +592,6 @@ ``` | ||
import { fontWeight } from 'styled-system' | ||
// <Text fontWeight='bold' /> | ||
``` | ||
```jsx | ||
<Text fontWeight='bold' /> | ||
// props.theme.fontWeights.bold | ||
@@ -276,3 +604,6 @@ ``` | ||
import { letterSpacing } from 'styled-system' | ||
// <Text letterSpacing={1} /> | ||
``` | ||
```jsx | ||
<Text letterSpacing={1} /> | ||
// props.theme.letterSpacings[1] | ||
@@ -285,4 +616,6 @@ ``` | ||
import { alignItems } from 'styled-system' | ||
// <Flex align='center' /> | ||
``` | ||
```jsx | ||
<Flex align='center' /> | ||
``` | ||
@@ -293,4 +626,6 @@ ### justifyContent (responsive) | ||
import { justifyContent } from 'styled-system' | ||
// <Flex justify='center' /> | ||
``` | ||
```jsx | ||
<Flex justify='center' /> | ||
``` | ||
@@ -301,4 +636,6 @@ ### flexWrap (responsive) | ||
import { flexWrap } from 'styled-system' | ||
// <Flex wrap /> | ||
``` | ||
```jsx | ||
<Flex wrap /> | ||
``` | ||
@@ -309,4 +646,6 @@ ### flexDirection (responsive) | ||
import { flexDirection } from 'styled-system' | ||
// <Flex flexDirection='column' /> | ||
``` | ||
```jsx | ||
<Flex flexDirection='column' /> | ||
``` | ||
@@ -317,4 +656,6 @@ ### flex (responsive) | ||
import { flex } from 'styled-system' | ||
// <Box flex='none' /> | ||
``` | ||
```jsx | ||
<Box flex='none' /> | ||
``` | ||
@@ -325,4 +666,6 @@ ### alignSelf (responsive) | ||
import { alignSelf } from 'styled-system' | ||
// <Box alignSelf='baseline' /> | ||
``` | ||
```jsx | ||
<Box alignSelf='baseline' /> | ||
``` | ||
@@ -333,3 +676,5 @@ ### borderRadius | ||
import { borderRadius } from 'styled-system' | ||
// <Box borderRadius={1} /> | ||
``` | ||
```jsx | ||
<Box borderRadius={1} /> | ||
// props.theme.radii[1] | ||
@@ -342,3 +687,5 @@ ``` | ||
import { borderColor } from 'styled-system' | ||
// <Box borderColor='blue' /> | ||
``` | ||
```jsx | ||
<Box borderColor='blue' /> | ||
// props.theme.colors.blue | ||
@@ -351,3 +698,5 @@ ``` | ||
import { borderWidth } from 'styled-system' | ||
// <Box borderWidth={1} /> | ||
``` | ||
```jsx | ||
<Box borderWidth={1} /> | ||
// props.theme.borderWidths | ||
@@ -368,8 +717,21 @@ ``` | ||
import { boxShadow } from 'styled-system' | ||
// <Box boxShadow={1} /> | ||
``` | ||
```jsx | ||
<Box boxShadow={1} /> | ||
// props.theme.shadows[1] | ||
// -- OR -- | ||
// <Box boxShadow={'1px 1px 0 black'} /> | ||
``` | ||
```jsx | ||
<Box boxShadow='large' /> | ||
// props.theme.shadows.large | ||
``` | ||
```jsx | ||
// raw value | ||
<Box boxShadow='1px 1px 0 black' /> | ||
``` | ||
## Pseudo-classes | ||
Pseudo-class utility props accept style objects that can pick up certain values, such as color, from a theme. | ||
### hover | ||
@@ -379,3 +741,10 @@ | ||
import { hover } from 'styled-system' | ||
// <Box hover={{ color: 'blue' }} /> | ||
``` | ||
```jsx | ||
<Box | ||
hover={{ | ||
textDecoration: 'underline', | ||
color: 'blue' | ||
}} | ||
/> | ||
// props.theme.colors.blue | ||
@@ -388,3 +757,5 @@ ``` | ||
import { focus } from 'styled-system' | ||
// <Box focus={{ color: 'blue' }} /> | ||
``` | ||
```jsx | ||
<Box focus={{ color: 'blue' }} /> | ||
// props.theme.colors.blue | ||
@@ -397,3 +768,5 @@ ``` | ||
import { active } from 'styled-system' | ||
// <Box active={{ color: 'navy' }} /> | ||
``` | ||
```jsx | ||
<Box active={{ color: 'navy' }} /> | ||
// props.theme.colors.navy | ||
@@ -406,3 +779,5 @@ ``` | ||
import { disabled } from 'styled-system' | ||
// <Box disabledStyle={{ color: 'gray' }} /> | ||
``` | ||
```jsx | ||
<Box disabledStyle={{ color: 'gray' }} /> | ||
// props.theme.colors.gray | ||
@@ -413,2 +788,37 @@ ``` | ||
## Table of Style Props | ||
Function Name | Prop | CSS Property | Theme Field | Responsive | ||
--------------|------------|-----------------|--------------|----------- | ||
`space` | `m` | `margin` | `space` | yes | ||
`space` | `mt` | `margin-top` | `space` | yes | ||
`space` | `mr` | `margin-right` | `space` | yes | ||
`space` | `mb` | `margin-bottom` | `space` | yes | ||
`space` | `ml` | `margin-left` | `space` | yes | ||
`space` | `p` | `padding` | `space` | yes | ||
`space` | `pt` | `padding-top` | `space` | yes | ||
`space` | `pr` | `padding-right` | `space` | yes | ||
`space` | `pb` | `padding-bottom` | `space` | yes | ||
`space` | `pl` | `padding-left` | `space` | yes | ||
`width` | `width` `w` | `width` | none | yes | ||
`fontSize` | `fontSize` `f`|`font-size` |`fontSizes` | yes | ||
`color` | `color` | `color` | `colors` | yes | ||
`color` | `bg` | `background-color`| `colors` | yes | ||
`textAlign` | `align` | `text-align` | none | yes | ||
`lineHeight` | `lineHeight` | `line-height` | `lineHeights` | no | ||
`fontWeight` | `fontWeight` | `font-weight` | `fontWeights` | no | ||
`letterSpacing` | `letterSpacing` | `letter-spacing` | `letterSpacings` | no | ||
`alignItems` | `align` | `align-items` | none | yes | ||
`justifyContent` | `justify` | `justify-content` | none | yes | ||
`flexWrap` | `wrap` (boolean) | `flex-wrap` | none | yes | ||
`flexDirection` | `flexDirection` | `flex-direction` | none | yes | ||
`flex` | `flex` | `flex` (shorthand) | none | yes | ||
`alignSelf` | `alignSelf` | `align-self` | none | yes | ||
`borderRadius` | `borderRadius` | `border-radius` | `radii` | no | ||
`borderColor` | `borderColor` | `border-color` | `colors` | no | ||
`borderWidth` | `borderWidth` | `border-width` | `borderWidths` | no | ||
`boxShadow` | `boxShadow` | `box-shadow` | `shadows` | no | ||
--- | ||
## Utilities | ||
@@ -418,6 +828,13 @@ | ||
The theme function can be used in any style declaration to get a value | ||
The theme function is an existential getter function | ||
that can be used in any style declaration to get a value | ||
from your theme, with support for fallback values. | ||
This helps prevent errors from throwing when a theme value is missing, | ||
which can be helpful when unit testing styled-components. | ||
```js | ||
theme(objectPath, fallbackValue) | ||
``` | ||
```js | ||
import styled from 'styled-components' | ||
@@ -434,2 +851,3 @@ import { theme } from 'styled-system' | ||
Prop type definitions are available for each style function to add to your component's propTypes object. | ||
Each value in `propTypes` is an object which should be assigned (or spread) to the component's `propTypes`. | ||
@@ -464,2 +882,3 @@ ```jsx | ||
// props that are defined as propTypes are removed | ||
CleanDiv.propTypes = { | ||
@@ -478,33 +897,30 @@ ...propTypes.textAlign | ||
### removeProps | ||
**Manually omitting props** | ||
This is an alternative to the `cleanElement` utility for removing style props from HTML. | ||
As an alternative to using the `cleanElement` function, removing style props from styled-components can be done manually, with a more React-like approach. | ||
```jsx | ||
```js | ||
import React from 'react' | ||
import styled from 'styled-components' | ||
import { | ||
width, | ||
fontSize, | ||
space, | ||
removeProps | ||
} from 'styled-system' | ||
import { width, color } from' styled-system' | ||
const BaseComponent = props => { | ||
const next = removeProps(props) | ||
return <div {...next} /> | ||
} | ||
const Component = styled(BaseComponent)([], | ||
const Box = styled(({ | ||
width, | ||
fontSize, | ||
space | ||
) | ||
color, | ||
bg, | ||
...props | ||
}) => <div {...props} />)` | ||
${width} | ||
${color} | ||
` | ||
``` | ||
See this discussion for more information: | ||
https://github.com/styled-components/styled-components/issues/439 | ||
--- | ||
## Low-level style functions | ||
## Low-level Style Functions | ||
To convert other CSS properties into styled-system props, | ||
To create custom utilities for other CSS properties, | ||
use the following low-level utility functions. | ||
@@ -514,3 +930,3 @@ | ||
Sets non-responsive styles using thematic values, based on props. | ||
Create a non-responsive style utility. | ||
@@ -528,2 +944,4 @@ ```js | ||
key: 'shadows' | ||
// convert number values to pixels | ||
numberToPx: false | ||
}) | ||
@@ -545,3 +963,3 @@ | ||
The `responsiveStyle` utility can be used to handle array-based responsive style props for other CSS properties. | ||
Create a responsive style utility that accepts array-based responsive prop values. | ||
@@ -552,17 +970,17 @@ ```js | ||
const flexDirection = responsiveStyle({ | ||
prop: 'direction', | ||
cssProperty: 'flexDirection' | ||
const borderRadius = responsiveStyle({ | ||
prop: 'borderRadius', | ||
cssProperty: 'borderRadius', | ||
// convert number values to pixels | ||
numberToPx: true, | ||
// set a key for values in theme | ||
key: 'radii' | ||
}) | ||
const Flex = styled.div` | ||
display: flex; | ||
${flexDirection} | ||
const RoundedBox = styled.div` | ||
${borderRadius} | ||
` | ||
const App = props => ( | ||
<Flex direction={[ 'column', 'row' ]}> | ||
<div>Responsive</div> | ||
<div>Direction</div> | ||
</Flex> | ||
<RoundedBox borderRadius={[ 0, 2 ]} /> | ||
) | ||
@@ -573,3 +991,3 @@ ``` | ||
Adds style props for pseudoclasses like `hover`, `focus`, `active`, etc. | ||
Create a pseudo-class style utility that accepts a style object prop value. | ||
@@ -597,18 +1015,25 @@ ```js | ||
## system-components | ||
For an even simpler authoring experience when using styled-system with styled-components, see [system-components](https://github.com/jxnblk/system-components), which is a lightweight wrapper around the two libraries. | ||
```js | ||
import system from 'system-components' | ||
// creates a Box component with default props tied to your theme | ||
const Box = system({ | ||
p: 2, | ||
bg: 'blue' | ||
}) | ||
``` | ||
--- | ||
## Default Theme | ||
### Default Theme | ||
If no theme is provided, styled-system uses smart defaults for breakpoints, the typographic scale, and the spacing scale. | ||
## Breakpoints | ||
styled-system uses a mobile-first responsive approach, | ||
where any value set works from that breakpoint and wider. | ||
The default set of breakpoints aims to cover a wide range of devices from mobile to desktop. | ||
Breakpoints default to `em` but can be overridden by passing strings with unit appended. | ||
Breakpoints can be customized using styled-components' [ThemeProvider](#configuration). | ||
```js | ||
[ 40, 52, 64 ] | ||
// Breakpoints | ||
const breakpoints = [ '40em', '52em', '64em' ] | ||
// @media screen and (min-width: 40em) | ||
@@ -618,70 +1043,40 @@ // @media screen and (min-width: 52em) | ||
[ '300px', '600px', '1200px' ] | ||
// @media screen and (min-width: 300px) | ||
// @media screen and (min-width: 600px) | ||
// @media screen and (min-width: 1200px) | ||
``` | ||
// Other units work as well, but em units are recommended | ||
// const breakpoints = [ '300px', '600px', '1200px' ] | ||
## Font Size Scale | ||
// Typographic Scale | ||
// numbers are converted to px values | ||
const fontSizes = [ 12, 14, 16, 20, 24, 32, 48, 64, 72 ] | ||
Using a typographic scale helps create visual rhythm and reduces the | ||
number of decisions needed when designing UI. | ||
Styled system uses a modular scale that covers most of a UI's needs, | ||
but it can be customized with styled-components' [ThemeProvider](#configuration). | ||
```js | ||
[ 12, 14, 16, 20, 24, 32, 48, 64, 72 ] | ||
// Spacing Scale | ||
// used for margin and padding | ||
const space = [ 0, 8, 16, 32, 64 ] | ||
``` | ||
## Spacing Scale | ||
--- | ||
Using a scale for spacing helps ensure elements line up, even when nested inside one another. | ||
styled-system uses a spacing scale based on an 8px, powers-of-two grid for margin and padding | ||
by default and can be customized with styled-components' [ThemeProvider](#configuration). | ||
### Troubleshooting | ||
```js | ||
[ 0, 8, 16, 32, 64 ] | ||
``` | ||
#### Unknown attribute warnings in React 16 | ||
## Configuration | ||
See [`cleanElement`](#cleanelement) | ||
styled-system can be configured with styled-components' (or other library's) | ||
[ThemeProvider](https://www.styled-components.com/docs/advanced#theming) | ||
#### Issues with prop-types | ||
As opposed to the built-in configurations, arrays given to the `breakpoints`, `space`, and | ||
`fontSizes` theme properties can be of arbitrary lengths. | ||
If you encounter issues while using this library alongside the `prop-types` npm package, | ||
webpack's [`resolve.modules`](https://webpack.js.org/configuration/resolve/#resolve-modules) | ||
option might be misconfigured using a relative (instead of absolute) path. | ||
This changes the way CommonJS modules work in a way that will likely cause other issues, | ||
and it's recommended that you only use absolute paths with the `resolve.modules` option. | ||
```jsx | ||
import { ThemeProvider } from 'styled-components' | ||
import MyComponent from './MyComponent' | ||
If you're using `resolve.modules` to avoid import syntax with lots of directory changes, | ||
you might want to consider using a flatter or better organized folder structure in your app. | ||
const theme = { | ||
breakpoints: [ | ||
32, 48, 64 | ||
], | ||
space: [ | ||
0, 6, 12, 18, 24 | ||
], | ||
fontSizes: [ | ||
12, 16, 18, 24, 36, 72 | ||
], | ||
colors: { | ||
black: '#111', | ||
blue: '#07c', | ||
} | ||
} | ||
See https://github.com/jxnblk/grid-styled/issues/51#issuecomment-336116426 | ||
const App = props => ( | ||
<ThemeProvider theme={theme}> | ||
<MyComponent | ||
fontSize={4} | ||
my={[ 2, 3 ]} | ||
color='blue' | ||
/> | ||
</ThemeProvider> | ||
) | ||
``` | ||
--- | ||
## Related | ||
- [system-components](https://github.com/jxnblk/system-components) | ||
- [grid-styled](https://github.com/jxnblk/grid-styled) | ||
@@ -701,3 +1096,5 @@ - [Rebass](http://jxnblk.com/rebass) | ||
MIT License | ||
--- | ||
[MIT License](LICENSE.md) | ||
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
51389
36
1056
24