Styled System

Responsive, theme-based style props for building design systems with React

gh stars Build Status Downloads Version size MIT License

  • Add style props that hook into your own theme
  • Quickly set responsive font-size, margin, padding, width, and more with props
  • Influenced by constraint-based design system principles
  • Typographic scale
  • Spacing scale for margin and padding
  • Works with any color palette
  • Works with most CSS-in-JS libraries, including styled-components and emotion
  • Used in Rebass, Rebass Grid, and the Priceline Design System
Style Props
const Box = styled.div(space, fontSize, width, color)

render(
  <Box
    mb={3}
    p={[ 3, 4 ]}
    fontSize={[ 4, 5, 6 ]}
    color='white'
    bg='magenta'>
    Style Props
  </Box>
)

Getting Started

Styled-system is a collection of utility functions that add style props to your React components, which allows for controlling styles based on global theme constants.

To use styled-system, you'll most likely want to use a CSS-in-JS library. These examples use styled-components, but styled-system works with other libraries like emotion and glamorous as well.

Create a Component

Create a new component that uses style functions from styled-system. To start with, add the color function to the component's styles argument.

Now, this component will have two style props available: color to set foreground color, and bg to set background color.

So far, this component can be styled with any valid CSS color. To create a more consistent UI, create a theme module with a colors object.

Theming

Most CSS-in-JS libraries use a ThemeProvider to handle theming in React. Import the styled-components ThemeProvider in the root of your application and pass the theme to the theme prop.

With the ThemeProvider, the Box component now has access to the colors defined in the theme object.

Styled-system will attempt to find a value based on keys in the theme and fallback to the raw value if it's not defined in the theme.

To make the Box component a little more useful, add a few more styled-system functions to handle layout styles.

Margin & Padding

The space function adds margin and padding props. The margin and padding props use a shorthand syntax, similar to Basscss, Tachyons, and Bootstrap.

Margin Props

  • m margin
  • mt margin-top
  • mr margin-right
  • mb margin-bottom
  • ml margin-left
  • mx margin-left and margin-right
  • my margin-top and margin-bottom

Padding Props

  • p padding
  • pt padding-top
  • pr padding-right
  • pb padding-bottom
  • pl padding-left
  • px padding-left and padding-right
  • py padding-top and padding-bottom

Space Theming

To set a consistent white-space scale, add a space array to your theme. Use numbers to set pixel values, or use strings for other CSS units such as rem.

All spacing props accept numbers, strings, or arrays as values, where:

  • Numbers between 0 and the last index of the space array are values from the space array defined in theme
  • Numbers greater than the length of the space array are converted to pixels
  • String values can be used for any valid CSS value (e.g. 'auto' or '2em')
  • Margin props accept negative values to set negative margin
  • Arrays can be used for responsive styles

Width

The width function adds a single width prop for setting responsive width styles.

The width prop accepts number, string, or array values, where:

  • Numbers between 0 and 1 are converted to percentage based widths (e.g. 1/2 becomes '50%')
  • Numbers greater than 1 are converted to pixels
  • Strings can be used for other CSS values (e.g. '50vw' or '30em')
  • Arrays can be used for responsive styles

Responsive Styles

All styled-system functions accept arrays as values to set styles responsively using a mobile-first approach.

Docs

Read more about how to use Styled System to build flexible design systems in the docs:


MIT License | GitHub | npm | Made by Jxnblk