styled-system
Advanced tools
Design system utilities for styled-components, glamorous, and other css-in-js libraries
Styled System is a utility for creating consistent, responsive, and theme-based design systems in React. It provides a set of functions and utilities to style components using a system of design tokens, such as spacing, colors, and typography, making it easier to build UI components that adhere to a design system.
Responsive Styles
Styled System allows you to define responsive styles using arrays. The `p` prop sets padding, `bg` sets background color, and `width` sets the width of the component. The values in the arrays correspond to different breakpoints.
const Box = styled.div`
${space}
${color}
${layout}
`;
<Box p={[1, 2, 3]} bg={['red', 'green', 'blue']} width={[1, 1/2, 1/4]} />Theme-based Design
Styled System integrates with a theme object to provide consistent styling across your application. The `color` and `space` utilities use the theme to apply styles.
const theme = {
colors: {
primary: 'blue',
secondary: 'green',
},
space: [0, 4, 8, 16, 32],
};
const Box = styled.div`
${color}
${space}
`;
<Box color='primary' p={2} />Utility Functions
Styled System provides utility functions like `space`, `color`, and `layout` that can be used to style components. These functions map props to CSS properties based on the theme.
import { space, color, layout } from 'styled-system';
const Box = styled.div`
${space}
${color}
${layout}
`;
<Box m={2} p={3} bg='primary' width={1/2} />Emotion is a library designed for writing CSS styles with JavaScript. It provides powerful and flexible styling capabilities, including support for theming and responsive styles. Compared to Styled System, Emotion offers more granular control over CSS but requires more manual setup for design systems.
Styled-components is a library for styling React components using tagged template literals. It allows for writing actual CSS to style components and supports theming and dynamic styling. While it doesn't provide the same utility functions as Styled System, it can be used in conjunction with Styled System for a more comprehensive solution.
Tailwind CSS is a utility-first CSS framework that provides low-level utility classes for building custom designs. It offers a different approach compared to Styled System by using predefined classes instead of JavaScript functions. Tailwind CSS is highly customizable and can be used to create responsive and theme-based designs.
Design system utilities for styled-components and other css-in-js libraries
npm i styled-system
"The future of css-in-js is going to look something like styled-system with its responsive values."
– Kye Hohenberger
"Coming from @tachyons_css, the styled-system utilities from @jxnblk is the missing link I’ve been looking for."
– Nathan Young
// Example uses styled-components,
// but styled-system works with most other css-in-js libraries as well
import styled from 'styled-components'
import { space, width, fontSize, color } from 'styled-system'
// Add styled-system functions to your component
const Box = styled.div`
${space}
${width}
${fontSize}
${color}
`
Each style function exposes its own set of props that style elements based on values defined in a theme.
// width: 50%
<Box width={1/2} />
// font-size: 20px
<Box fontSize={4} />
// margin: 16px
<Box m={2} />
// padding: 32px
<Box p={3} />
// color
<Box color='tomato' />
<Box color='grays.0' />
// background color
<Box bg='tomato' />
Set responsive width, margin, padding, font-size, and other properties with a shorthand array syntax. Read more
// responsive width
<Box width={[ 1, 1/2, 1/4 ]} />
// responsive font-size
<Box fontSize={[ 2, 3, 4 ]} />
// responsive margin
<Box m={[ 1, 2, 3 ]} />
// responsive padding
<Box p={[ 1, 2, 3 ]} />
import { space } from 'styled-system'
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. 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.
Margin and padding props follow a shorthand syntax for specifying direction.
m: marginmt: margin-topmr: margin-rightmb: margin-bottomml: margin-leftmx: margin-left and margin-rightmy: margin-top and margin-bottomp: paddingpt: padding-toppr: padding-rightpb: padding-bottompl: padding-leftpx: padding-left and padding-rightpy: padding-top and padding-bottomimport { width } from 'styled-system'
The width utility parses a component's width prop and converts it into a CSS width declaration.
import { fontSize } from 'styled-system'
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.
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.
import { color } from 'styled-system'
The color utility parses a component's color and bg props and converts them into CSS declarations.
By default the raw value of the prop is returned.
Color palettes can be configured with the ThemeProvider to use keys as prop values, with support for dot notation.
Array values are converted into responsive values.
All core function props accept arrays as values for mobile-first responsive styles.
<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 ]} />
These functions are for adding other theme-based style props to a component. For practical reasons, some props do not accept arrays for responsive styles.
import { textAlign } from 'styled-system'
// <Text align='center' />
import { lineHeight } from 'styled-system'
// <Text lineHeight={1} />
// props.theme.lineHeights[1]
import { fontWeight } from 'styled-system'
// <Text fontWeight='bold' />
// props.theme.fontWeights.bold
import { letterSpacing } from 'styled-system'
// <Text letterSpacing={1} />
// props.theme.letterSpacings[1]
import { alignItems } from 'styled-system'
// <Flex align='center' />
import { justifyContent } from 'styled-system'
// <Flex justify='center' />
import { flexWrap } from 'styled-system'
// <Flex wrap />
import { flexDirection } from 'styled-system'
// <Flex flexDirection='column' />
import { flex } from 'styled-system'
// <Box flex='none' />
import { alignSelf } from 'styled-system'
// <Box alignSelf='baseline' />
import { borderRadius } from 'styled-system'
// <Box borderRadius={1} />
// props.theme.radii[1]
import { borderColor } from 'styled-system'
// <Box borderColor='blue' />
// props.theme.colors.blue
import { borderWidth } from 'styled-system'
// <Box borderWidth={1} />
// props.theme.borderWidths
// Only apply border in one direction
<Box borderWidth={1} borderBottom />
// Or in multiple directions
<Box borderWidth={1} borderTop borderBottom />
import { boxShadow } from 'styled-system'
// <Box boxShadow={1} />
// props.theme.shadows[1]
// -- OR --
// <Box boxShadow={'1px 1px 0 black'} />
import { hover } from 'styled-system'
// <Box hover={{ color: 'blue' }} />
// props.theme.colors.blue
import { focus } from 'styled-system'
// <Box focus={{ color: 'blue' }} />
// props.theme.colors.blue
import { active } from 'styled-system'
// <Box active={{ color: 'navy' }} />
// props.theme.colors.navy
import { disabled } from 'styled-system'
// <Box disabledStyle={{ color: 'gray' }} />
// props.theme.colors.gray
The theme function can be used in any style declaration to get a value from your theme, with support for fallback values.
import styled from 'styled-components'
import { theme } from 'styled-system'
const Box = styled.div`
border-radius: ${theme('radii.small')};
`
Prop type definitions are available for each style function to add to your component's propTypes object.
import styled from 'styled-components'
import { width, propTypes } from 'styled-system'
const Box = styled.div`
${width}
`
Box.propTypes = {
...propTypes.width
}
Styled-components and other libraries attempt to remove invalid HTML attributes from props using a whitelist,
but do not remove width, fontSize, color, or other valid HTML attributes when used as props.
To ensure that style props are not passed on to the underlying DOM element,
even in cases where a prop is a valid HTML attribute, like width or align, use the cleanElement higher order component to create a base component
that remove props defined in propTypes.
import styled from 'styled-components'
import { textAlign, propTypes, cleanElement } from 'styled-system'
const CleanDiv = cleanElement('div')
CleanDiv.propTypes = {
...propTypes.textAlign
}
const Box = styled(CleanDiv)`
${textAlign}
`
// <Box align='center' />
// `align` prop is picked up by styled-components,
// but not passed on to the HTML element
This is an alternative to the cleanElement utility for removing style props from HTML.
import React from 'react'
import styled from 'styled-components'
import {
width,
fontSize,
space,
removeProps
} from 'styled-system'
const BaseComponent = props => {
const next = removeProps(props)
return <div {...next} />
}
const Component = styled(BaseComponent)([],
width,
fontSize,
space
)
To convert other CSS properties into styled-system props, use the following low-level utility functions.
Sets non-responsive styles using thematic values, based on props.
import styled from 'styled-components'
import { style } from 'styled-system'
const textShadow = style({
// React prop name
prop: 'shadow',
// The corresponding CSS property
cssProperty: 'textShadow',
// set a key to find values from `props.theme`
key: 'shadows'
})
const ShadowText = styled(Text)`
${textShadow}
`
// with a `theme.shadows` array
const App = props => (
<ShadowText shadow={0}>
Shady
</ShadowText>
)
The responsiveStyle utility can be used to handle array-based responsive style props for other CSS properties.
import styled from 'styled-components'
import { responsiveStyle } from 'styled-system'
const flexDirection = responsiveStyle({
prop: 'direction',
cssProperty: 'flexDirection'
})
const Flex = styled.div`
display: flex;
${flexDirection}
`
const App = props => (
<Flex direction={[ 'column', 'row' ]}>
<div>Responsive</div>
<div>Direction</div>
</Flex>
)
Adds style props for pseudoclasses like hover, focus, active, etc.
import styled from 'styled-components'
import { pseudoStyle } from 'styled-system'
const checkedStyle = pseudoStyle('checked', 'checkedStyle')({
// keys for theme-based values
color: 'colors',
backgroundColor: 'colors',
})
const FancyCheckbox = styled.input`
/* ...base styles */
${checkedStyle}
`
FancyCheckbox.defaultProps = {
type: 'checkbox'
}
// <FancyCheckbox checkedStyle={{ backgroundColor: 'blue' }} />
If no theme is provided, styled-system uses smart defaults for breakpoints, the typographic scale, and the spacing scale.
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.
[ 40, 52, 64 ]
// @media screen and (min-width: 40em)
// @media screen and (min-width: 52em)
// @media screen and (min-width: 64em)
[ '300px', '600px', '1200px' ]
// @media screen and (min-width: 300px)
// @media screen and (min-width: 600px)
// @media screen and (min-width: 1200px)
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.
[ 12, 14, 16, 20, 24, 32, 48, 64, 72 ]
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.
[ 0, 8, 16, 32, 64 ]
styled-system can be configured with styled-components' (or other library's) ThemeProvider
As opposed to the built-in configurations, arrays given to the breakpoints, space, and
fontSizes theme properties can be of arbitrary lengths.
import { ThemeProvider } from 'styled-components'
import MyComponent from './MyComponent'
const theme = {
breakpoints: [
32, 48, 64
],
space: [
0, 6, 12, 18, 24
],
fontSizes: [
12, 16, 18, 24, 36, 72
],
colors: {
black: '#111',
blue: '#07c',
}
}
const App = props => (
<ThemeProvider theme={theme}>
<MyComponent
fontSize={4}
my={[ 2, 3 ]}
color='blue'
/>
</ThemeProvider>
)
MIT License
FAQs
Responsive, theme-based style props for building design systems with React
The npm package styled-system receives a total of 250,958 weekly downloads. As such, styled-system popularity was classified as popular.
We found that styled-system demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.